helloagents 2.3.4-beta.1 → 2.3.5-beta.1

package/README.md

@@ -8,7 +8,7 @@
 
 **Let AI go beyond analysis — keep pushing until implementation and verification are done.**
 
-[![Version](https://img.shields.io/badge/version-2.3.4-orange.svg)](./pyproject.toml)
+[![Version](https://img.shields.io/badge/version-2.3.5-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/commands-15-6366f1.svg)](./helloagents/functions)
@@ -24,10 +24,14 @@
 
 ---
 
+> [!IMPORTANT]
+> **Looking for the old version of HelloAGENTS?** The legacy codebase has been moved to a separate archive repository: [helloagents-archive](https://github.com/hellowind777/helloagents-archive)
+
 ## Table of Contents
 
 - [Before and After](#before-and-after)
 - [Core Features](#core-features)
+  - [Sub-Agent Native Mapping](#sub-agent-native-mapping)
 - [Quick Start](#quick-start)
 - [Configuration](#configuration)
 - [How It Works](#how-it-works)
@@ -39,6 +43,7 @@
 - [Version History](#version-history)
 - [Contributing](#contributing)
 - [License](#license)
+- [Next Steps](#next-steps)
 
 ## Before and After
 
@@ -112,6 +117,26 @@ L0 user memory (global preferences), L1 project knowledge base (structured docs
 **Your gain:** context survives across sessions and projects.
 </td>
 </tr>
+<tr>
+<td width="50%" valign="top">
+<img src="./readme_images/02-feature-icon-installer.svg" width="48" align="left">
+
+**Extensibility & Customization**
+
+Voice notifications (5 event sounds), custom command extension (`.helloagents/commands/*.md`), user-defined tool orchestration (sub-agents, skills, MCP servers, plugins), and flexible configuration options. All features work across 6 CLI targets with graceful degradation.
+
+**Your gain:** tailor the workflow to your team's needs without forking the codebase.
+</td>
+<td width="50%" valign="top">
+<img src="./readme_images/03-feature-icon-workflow.svg" width="48" align="left">
+
+**Multi-CLI Support**
+
+One rule set works across Claude Code, Codex CLI, OpenCode, Gemini CLI, Qwen CLI, and Grok CLI. Automatic feature detection and graceful degradation ensure consistent experience regardless of CLI capabilities.
+
+**Your gain:** switch between CLIs without relearning workflows or reconfiguring rules.
+</td>
+</tr>
 </table>
 
 ### Sub-Agent Native Mapping
@@ -125,10 +150,50 @@ L0 user memory (global preferences), L1 project knowledge base (structured docs
 | Qwen CLI | Built-in tool calls | Fallback to sequential execution |
 | Grok CLI | Built-in tool calls | Fallback to sequential execution |
 
-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.
+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 11 lifecycle hooks + Codex CLI notify hook + Gemini/Grok CLI hooks) with automatic graceful degradation when unavailable.
+
+### CLI Compatibility Quick Reference
+
+| CLI | Recommended Version | Key Features | Configuration Notes |
+|-----|-------------------|--------------|---------------------|
+| **Claude Code** | Latest | Agent Teams, 11 lifecycle hooks, auto-memory | Requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` for teams mode |
+| **Codex CLI** | 0.110+ | spawn_agent, CSV batch, collaboration_modes | Enable sub-agents, CSV orchestration, set `project_doc_max_bytes >= 131072` |
+| **OpenCode** | Latest | Built-in agent mode | Sequential execution fallback |
+| **Gemini CLI** | Latest | Built-in tool calls | Sequential execution fallback |
+| **Qwen CLI** | Latest | Built-in tool calls | Sequential execution fallback |
+| **Grok CLI** | Latest | Built-in tool calls | Sequential execution fallback |
+
+<details>
+<summary>📋 Detailed CLI-specific notes (click to expand)</summary>
+
+**Codex CLI Configuration:**
+- Enable sub-agents and CSV orchestration features
+- Set `project_doc_max_bytes = 131072` in config.toml
+- Configure `developer_instructions` for routing protocol priority
+- Enable `collaboration_modes` for TUI interactive selection (v0.110+)
+- Configure `nickname_candidates` for agent role identification
+- Configure CSV batch processing if using parallel workflows
+
+**Claude Code Setup:**
+- Set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` environment variable for Agent Teams
+- 11 lifecycle hooks auto-configured during installation (SessionStart, UserPromptSubmit, SubagentStart/Stop, PostToolUse, Stop, TeammateIdle, PreCompact, PreToolUse, SessionEnd, PostToolUseFailure)
+- Auto-memory feature enabled by default
+
+**Other CLIs:**
+- OpenCode/Gemini/Qwen/Grok use sequential execution fallback
+- All features work with graceful degradation
+- Hooks may not be available on all platforms
+
+</details>
 
 ## Quick Start
 
+> 💡 **Choose your installation method:**
+> - **First-time users** → Method A (one-line script, recommended)
+> - **Node.js developers** → Method B (npx)
+> - **Python developers** → Method D (pip)
+> - **Need isolated environment** → Method C (UV)
+
 > ⚠️ **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.
 
 > ⚠️ **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).
@@ -260,6 +325,7 @@ Additionally, HelloAGENTS provides: **five-dimension routing scoring** (action n
 > - Collab sub-agent scheduling requires Codex CLI feature gate to be enabled
 >
 > 💡 **Best practices:**
+> - Codex 0.110+ recommended for full feature set (collaboration_modes, nickname_candidates)
 > - 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
 
@@ -324,33 +390,109 @@ Customize workflow behavior via `config.json` after installation. Only include k
 
 > File missing or unparseable is silently skipped with defaults applied. Unknown keys produce a warning and are ignored.
 
+### Common Configuration Scenarios
+
+<details>
+<summary>📝 English-only projects</summary>
+
+```json
+{
+  "OUTPUT_LANGUAGE": "en-US",
+  "BILINGUAL_COMMIT": 0
+}
+```
+All AI outputs, KB files, and commit messages will be in English only.
+</details>
+
+<details>
+<summary>🚫 Disable automatic KB creation</summary>
+
+```json
+{
+  "KB_CREATE_MODE": 0
+}
+```
+Knowledge base won't be created automatically. Use `~init` command when needed.
+</details>
+
+<details>
+<summary>⚡ High-concurrency batch processing (Codex CLI)</summary>
+
+```json
+{
+  "CSV_BATCH_MAX": 32
+}
+```
+Increase parallel CSV batch processing from 16 to 32 (max 64). Requires Codex CLI with CSV orchestration enabled.
+</details>
+
+<details>
+<summary>🔕 Disable update checks</summary>
+
+```json
+{
+  "UPDATE_CHECK": 0
+}
+```
+Skip version update checks entirely (not recommended for production use).
+</details>
+
+<details>
+<summary>💬 One-shot clarification mode</summary>
+
+```json
+{
+  "EVAL_MODE": 2
+}
+```
+Ask all clarification questions at once (max 3) instead of progressive mode (1 question per round, max 5).
+</details>
+
 ## How It Works
 
-1. Install the package (script/pip/uv) and run `helloagents` to launch an interactive menu for selecting target CLIs (or specify directly with `helloagents install <target>`). Hooks and SKILL.md are auto-deployed during installation.
-2. In AI chat, every input is scored on five dimensions and routed to R0–R3.
-3. R2/R3 tasks enter the stage chain: EVALUATE → DESIGN → DEVELOP. R1 fast flow handles single-point operations directly.
-4. RLM dispatches native sub-agents and specialized roles based on task complexity. Tasks with dependencies are scheduled via DAG topological sort with layer-by-layer parallel dispatch.
-5. EHRB scans each step for destructive operations; risky actions require explicit user confirmation. Hooks provide additional pre-tool safety checks when available.
-6. Three-layer memory (user / project KB / session) preserves context across sessions.
-7. Stage chain completes with verified output and optional knowledge base sync.
+**In short:** HelloAGENTS automatically selects processing depth based on task complexity — simple questions get fast responses, complex tasks go through the full evaluate→design→develop flow, with safety checks and memory retention throughout.
+
+**Detailed flow:**
+
+1. **Install & Deploy** — Run `helloagents` to select target CLI, auto-deploys config files and hooks
+2. **Smart Routing** — Every input is auto-scored; simple queries get direct answers, complex tasks enter structured workflow
+3. **Stage Progression** — Complex tasks advance through "Evaluate → Design → Develop" stages, each with clear deliverables
+4. **Auto Orchestration** — System dispatches sub-agents and specialized roles based on complexity, parallelizes when possible
+5. **Safety Guard** — Each step scans for destructive operations, risky actions require user confirmation
+6. **Memory Retention** — User preferences, project knowledge, session context persist across sessions
+7. **Verified Completion** — Stage chain completes with verified output, auto-syncs knowledge base
 
 ## In-Chat Workflow Commands
 
 These commands run inside AI chat, not your system shell.
 
+**Common Commands:**
+
 | Command | Purpose |
 |---|---|
 | ~auto | full autonomous workflow |
 | ~plan | planning and package generation |
 | ~exec | execute existing package |
 | ~init | initialize knowledge base |
+| ~commit | generate commit message from context |
+| ~status / ~help | status and help |
+
+**Quality Checks:**
+
+| Command | Purpose |
+|---|---|
+| ~test | run project tests |
+| ~review | code review |
+| ~validatekb | validate knowledge base |
+
+**Advanced Features:**
+
+| Command | Purpose |
+|---|---|
 | ~upgradekb | upgrade knowledge structure |
 | ~clean / ~cleanplan | cleanup workflow artifacts |
-| ~test / ~review / ~validatekb | quality checks |
-| ~commit | generate commit message from context |
 | ~rollback | rollback workflow state |
 | ~rlm | role orchestration (spawn / agents / resume / team) |
-| ~status / ~help | status and help |
 
 ## Usage Guide
 
@@ -495,56 +637,186 @@ On the first response of each session, the system silently checks for new versio
 
 - AGENTS.md: router and workflow protocol
 - SKILL.md: skill discovery metadata for CLI targets
-- pyproject.toml: package metadata (v2.3.4)
+- pyproject.toml: package metadata (v2.3.5)
 - helloagents/cli.py: CLI entry point
 - helloagents/_common.py: shared constants and utilities
-- helloagents/core/: CLI management modules (install, uninstall, update, status)
+- helloagents/core/: CLI management modules (install, uninstall, update, status, dispatcher, hooks settings)
 - helloagents/functions: command definitions (15)
 - helloagents/stages: design, develop
 - helloagents/services: knowledge, package, memory and support services
-- helloagents/rules: state, cache, tools, scaling, evaluation, sub-agent protocols
+- helloagents/rules: state, cache, tools, scaling, sub-agent protocols
 - helloagents/rlm: role library and orchestration helpers
-- helloagents/hooks: Claude Code and Codex CLI hooks configs
-- helloagents/scripts: automation scripts
+- helloagents/hooks: Claude Code, Codex CLI, Gemini CLI, and Grok CLI hooks configs
+- helloagents/scripts: automation scripts (sound notify, progress snapshot, safety guard, etc.)
+- helloagents/agents: sub-agent definitions (5 RLM roles)
+- helloagents/commands: custom command templates
+- helloagents/assets: sound resources (5 event sounds)
 - helloagents/templates: KB and plan templates
 
 ## FAQ
 
-- Q: Is this a Python CLI tool or prompt package?
-  A: Both. CLI manages installation; workflow behavior comes from AGENTS.md and helloagents docs.
+**Q: Is this a Python CLI tool or prompt package?**
+
+A: Both. The CLI manages installation and updates, while the workflow behavior comes from AGENTS.md and documentation files. Think of it as a delivery system + intelligent workflow protocol.
+
+**Q: Which target should I install?**
+
+A: Choose the CLI you're actively using: `codex` (Codex CLI), `claude` (Claude Code), `gemini` (Gemini CLI), `qwen` (Qwen CLI), `grok` (Grok CLI), or `opencode` (OpenCode). You can install to multiple targets with `helloagents install --all`. See [CLI Compatibility Quick Reference](#cli-compatibility-quick-reference) for details.
+
+**Q: What if a rules file already exists?**
+
+A: HelloAGENTS automatically backs up non-HelloAGENTS files before replacement. Backups are timestamped and stored in your CLI's config directory. You can restore them anytime if needed.
+
+**Q: What is RLM?**
 
-- Q: Which target should I install?
-  A: Use the CLI you run: codex, claude, gemini, qwen, grok, or opencode.
+A: Role Language Model — HelloAGENTS's sub-agent orchestration system. It includes 5 specialized roles (reviewer, synthesizer, kb_keeper, pkg_keeper, writer) plus native CLI sub-agents. Tasks are scheduled via DAG dependency analysis with parallel execution when possible. Learn more in [Usage Guide](#usage-guide).
 
-- Q: What if a rules file already exists?
-  A: Non-HelloAGENTS files are backed up before replacement.
+**Q: Where does project knowledge go?**
 
-- Q: What is RLM?
-  A: Role Language Model — a sub-agent orchestration system with 5 specialized roles + native CLI sub-agents, DAG-based parallel scheduling, and standardized prompt/return format.
+A: In the project-local `.helloagents/` directory. The knowledge base auto-syncs when code changes (controlled by `KB_CREATE_MODE` config). It includes module docs, CHANGELOG, session summaries, and custom commands. See [KB Auto-Sync & CHANGELOG](#kb-auto-sync--changelog).
 
-- Q: Where does project knowledge go?
-  A: In the project-local `.helloagents/` directory, auto-synced when code changes.
+**Q: Does memory persist across sessions?**
 
-- Q: Does memory persist across sessions?
-  A: Yes. L0 user memory is global, L1 project KB is per-project, L2 session summaries are auto-saved at stage transitions.
+A: Yes, through three layers: L0 user memory (global preferences in `~/.helloagents/`), L1 project KB (per-project in `.helloagents/`), and L2 session summaries (auto-saved at stage transitions). Context survives even if you close and reopen your CLI.
 
-- Q: What are Hooks?
-  A: Lifecycle hooks auto-deployed during installation. Claude Code gets 9 event hooks (safety checks, progress snapshots, KB sync, etc.); Codex CLI gets a notify hook for update checks. All optional — features degrade gracefully without hooks.
+**Q: What are Hooks?**
 
-- Q: What is Agent Teams?
-  A: An experimental Claude Code multi-agent collaboration mode. Multiple Claude Code instances work as teammates with shared task lists and mailbox communication, mapped to RLM roles. Falls back to standard Task sub-agents when unavailable.
+A: Lifecycle hooks auto-deployed during installation. Claude Code gets 11 event hooks (safety checks, dangerous command guard, progress snapshots, KB sync, sound notifications, tool failure recovery, etc.); Codex CLI gets a notify hook for update and sound notifications; Gemini CLI and Grok CLI get hooks for context injection, progress snapshots, and sound notifications. All optional — features degrade gracefully when hooks aren't available. No manual configuration needed.
+
+**Q: What is Agent Teams?**
+
+A: An experimental Claude Code feature where multiple Claude Code instances collaborate as teammates with shared task lists and mailbox communication. Enable with `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. When unavailable, HelloAGENTS falls back to standard Task sub-agents. See [Multi-Terminal Collaboration](#multi-terminal-collaboration).
 
 ## Troubleshooting
 
-- command not found: ensure install path is in PATH
-- package version unknown: install package first for metadata
-- target not detected: launch target CLI once to create config directory
-- custom rules overwritten: restore from timestamped backup in CLI config dir
-- images not rendering: keep relative paths and commit readme_images files
+### Command not found
+
+**Problem:** `helloagents: command not found` after installation
+
+**Diagnosis:** Install path not in system PATH
+
+**Solution:**
+- UV: Restart terminal after UV installation
+- pip: Check `pip show helloagents` for install location, add to PATH
+- Verify with `which helloagents` (Unix) or `where helloagents` (Windows)
+
+**Verification:** Run `helloagents version`
+
+---
+
+### Package version unknown
+
+**Problem:** Version shows as "unknown"
+
+**Diagnosis:** Package metadata not available
+
+**Solution:** Install the package first: `pip install git+https://github.com/hellowind777/helloagents.git` or use UV/npx methods
+
+**Verification:** Run `helloagents version` — should show current version number
+
+---
+
+### Target not detected
+
+**Problem:** CLI target not found during installation
+
+**Diagnosis:** Config directory doesn't exist yet
+
+**Solution:** Launch the target CLI at least once to create its config directory, then retry `helloagents install <target>`
+
+**Verification:** Check config paths:
+- Codex CLI: `~/.codex/`
+- Claude Code: `~/.claude/`
+- Others: see CLI documentation
+
+---
+
+### Custom rules overwritten
+
+**Problem:** Custom rules replaced by HelloAGENTS
+
+**Diagnosis:** Installation replaces existing files
+
+**Solution:** Restore from timestamped backup in CLI config directory (e.g., `~/.codex/rules/AGENTS.md.backup.20260304_132146`)
+
+**Verification:** Check backup files in config directory
+
+---
+
+### Images not rendering
+
+**Problem:** README images don't display
+
+**Diagnosis:** Missing image files or incorrect paths
+
+**Solution:**
+- Keep relative paths in README (e.g., `./readme_images/`)
+- Ensure `readme_images/` folder is committed to repository
+- Verify image files exist locally
+
+**Verification:** Check `ls readme_images/` shows all referenced images
+
+---
+
+### CCswitch replaces HelloAGENTS config
+
+**Problem:** After switching CCswitch profiles, HelloAGENTS stops working (workflow commands unrecognized, hooks not firing, rules missing)
+
+**Diagnosis:** CCswitch replaces the entire CLI config directory (e.g., `~/.claude/`) when switching profiles, overwriting HelloAGENTS's hooks, permissions, and rule files
+
+**Solution:** After switching CCswitch profiles, run one of these commands to restore HelloAGENTS:
+
+    helloagents install claude    # reinstall to specific CLI target
+    helloagents update            # update + auto-sync all installed targets
+
+**Prevention:** v2.3.5 adds automatic configuration integrity check on session start — if HelloAGENTS config is missing or corrupted, a warning is displayed with recovery instructions
+
+**Verification:** Run `helloagents status` to confirm all targets show as installed
+
+---
+
+### CCswitch configuration conflict
+
+**Problem:** HelloAGENTS config reappears after uninstall when switching CCswitch profiles
+
+**Diagnosis:** CCswitch saved HelloAGENTS settings before uninstall
+
+**Solution:** After uninstalling HelloAGENTS, manually clean up HelloAGENTS-related settings (hooks, permissions, rules) from all saved CCswitch profiles
+
+**Verification:** Check CCswitch profile directories for HelloAGENTS remnants
 
 ## Version History
 
-### v2.3.4 (current)
+### v2.3.5 (current)
+
+**New Features:**
+- Voice notification system with 5 event sounds (complete, idle, confirm, error, warning) across Windows/macOS/Linux, with smart two-layer routing (stop_reason + G3 format icon detection)
+- Claude Code hooks expanded from 9 to 11 lifecycle event types: added dangerous command guard (PreToolUse), session end cleanup (SessionEnd), and tool failure recovery suggestions (PostToolUseFailure)
+- Hooks support expanded to Gemini CLI and Grok CLI (SessionStart, BeforeAgent/AfterAgent, PreCompress, PreToolUse, PostToolUse)
+- Codex CLI 0.110 features: `collaboration_modes` for TUI interactive selection, `nickname_candidates` for agent role identification
+- Configuration integrity check on session start (auto-detect config corruption or replacement by CCswitch etc.)
+- Context compression pre-save with automatic progress snapshot (pre_compact.py, progress_snapshot.py — actual implementations replacing placeholder hooks)
+- User-defined tool registration and orchestration — intelligent invocation of custom sub-agents, skills, MCP servers, and plugins
+- Custom command extension support via `.helloagents/commands/*.md`
+
+**Improvements:**
+- Comprehensive audit fixes (21 issues: 6 HIGH + 9 MEDIUM + 6 LOW)
+  - Code quality: extracted 5 shared utility functions, eliminated circular dependencies
+  - Cross-platform: unified platform detection, consistent encoding handling
+  - Security: configuration backup before overwrite, placeholder validation
+  - Documentation: configuration rationale, compatibility verification notes
+- Core architecture: new dispatcher module, Codex roles definition, Claude rules management, hooks settings manager
+- Install/update script refactoring with persistent configuration
+- Voice notification accuracy and false positive reduction (Codex client filtering, Windows sync playback)
+- Sub-agent nickname optimization across CLIs
+- Codex CLI interactive menu, persistent memory, and context compression optimization
+- R2 simplified flow and evaluation module re-integration
+- Context compression state persistence optimization
+- Tool/Shell usage optimization
+- CCswitch compatibility notes for configuration cleanup after uninstall
+- SKILL discovery entry optimization
+
+### v2.3.4
 
 - Split 3 oversized files (>450 lines) into 6 independent modules
 - Consolidated 9 CLI management scripts into core/ subpackage
@@ -552,14 +824,6 @@ On the first response of each session, the system silently checks for new versio
 - Removed redundant backward-compatible re-exports
 - Elevated Codex CLI routing protocol priority to prevent system prompt override
 
-### v2.3.3
-
-- 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
@@ -572,19 +836,6 @@ On the first response of each session, the system silently checks for new versio
 - 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
-- Proposal evaluation criteria optimized: user value weight is always no less than any other single dimension, evaluation dimensions dynamically adjusted by project context
-- Universal task type support: generalized evaluation, follow-up, and proposal design terminology from programming-specific to documents, design, general tasks and more
-- Added sub-agent DAG dependency scheduling with topological sort, layer-by-layer parallel dispatch, and failure propagation
-- Dynamic sub-agent parallel count based on independent work units, eliminated hardcoded limits
-- Unified output format: structured display for score breakdowns, follow-up options, and confirmation messages
-- Streamlined execution paths with shorter stage chains and step-level on-demand module loading
-- 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
-
 ## Contributing
 
 See CONTRIBUTING.md for contribution rules and PR checklist.
@@ -593,6 +844,23 @@ See CONTRIBUTING.md for contribution rules and PR checklist.
 
 This project is dual-licensed: Code under Apache-2.0, Documentation under CC BY 4.0. See [LICENSE.md](./LICENSE.md).
 
+## Next Steps
+
+**Getting Started:**
+- Install HelloAGENTS using your preferred method: [Quick Start](#quick-start)
+- Try `~auto` with a simple task to see the full workflow in action
+- Explore `~plan` + `~exec` for more control over the process
+
+**Learn More:**
+- Read [Usage Guide](#usage-guide) for detailed workflow patterns
+- Check [Configuration](#configuration) to customize behavior
+- Review [In-Chat Workflow Commands](#in-chat-workflow-commands) reference
+
+**Community & Support:**
+- Star the repo if HelloAGENTS helps your workflow
+- Report issues or request features on [GitHub Issues](https://github.com/hellowind777/helloagents/issues)
+- Contribute improvements: see [CONTRIBUTING.md](./CONTRIBUTING.md)
+
 ---
 
 <div align="center">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "2.3.4-beta.1",
+  "version": "2.3.5-beta.1",
   "type": "module",
   "description": "HelloAGENTS - AI-native sub-agent orchestration framework for multi-CLI environments",
   "author": "HelloWind",