helloagents 3.0.2-beta.1 → 3.0.7

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "helloagents",
       "description": "Quality-driven orchestration kernel for AI CLIs: intelligent routing, quality verification, safety guards, and notifications",
-      "version": "3.0.2-beta.1",
+      "version": "3.0.7",
       "source": "./",
       "author": {
         "name": "HelloWind",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.2-beta.1",
+  "version": "3.0.7",
   "description": "HelloAGENTS — The orchestration kernel that makes any AI CLI smarter. Adds intelligent routing, quality verification (Ralph Loop), safety guards, and notifications.",
   "author": "HelloWind",
   "license": "Apache-2.0",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.2-beta.1",
+  "version": "3.0.7",
   "description": "HelloAGENTS — Quality-driven orchestration kernel for AI CLIs with intelligent routing, quality verification (Ralph Loop), safety guards, and notifications.",
   "author": {
     "name": "HelloWind",

package/README.md

@@ -8,7 +8,7 @@
 
 **Quality-driven orchestration kernel for AI coding CLIs — 14 auto-activated skills, process discipline, and checklist gating.**
 
-[![Version](https://img.shields.io/badge/version-3.0.2-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.7-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)
@@ -33,6 +33,7 @@
 <summary><strong>Click to expand</strong></summary>
 
 - [🎯 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)
@@ -90,6 +91,25 @@ HelloAGENTS fixes that. It's an orchestration layer that sits on top of your AI
 - ❌ Simple one-off questions (HelloAGENTS adds process overhead)
 - ❌ Non-coding tasks (optimized for software engineering)
 
+## 🆚 Compared with v2.3.8
+
+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.
+
+| Dimension | v2.3.8 | Local `v3.0.7` |
+|-----------|--------|----------------|
+| **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 orchestration kernel for AI CLIs, centered on routing, gating, 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 routed kernel |
+| **Command surface** | 15 commands including `~exec`, `~rollback`, `~rlm`, `~validatekb` | 12 focused commands such as `~idea`, `~plan`, `~build`, `~verify`, `~prd`, `~loop`, and `~wiki` |
+| **Quality model** | More distributed rules, more reliance on prose | 14 auto-activated skills + checklist gating + Ralph Loop + structured evidence |
+| **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 |
+
+In one sentence: `v2.3.8` was closer to "workflow glue for multiple CLIs"; `v3.0.7` is a real orchestration kernel that unifies quality rules, plan artifacts, verification evidence, and installation lifecycle into one operating model.
+
 ## ✨ Core Features
 
 HelloAGENTS enforces quality through three mechanisms working together:
@@ -136,10 +156,32 @@ L1 blocks destructive commands (`rm -rf /`, `git push --force`, `DROP DATABASE`)
 
 **⚡ Structured Workflow**
 
-Simple tasks get direct execution. Complex tasks go through ORIENT → CLARIFY → PLAN → EXECUTE → VALIDATE with interactive design, solution proposals, and plan packages.
+Simple tasks stay fast. Complex tasks use a routed kernel workflow: ROUTE/TIER → SPEC → PLAN → BUILD → VERIFY → CONSOLIDATE, with explicit command lanes for ideation, planning, implementation, and validation.
 
 **Your gain:** proportional effort — quick tasks stay fast, complex tasks get full process.
 
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+<img src="./readme_images/02-feature-icon-installer.svg" width="48" align="left">
+
+**🧠 Structured Plan Artifacts**
+
+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.
+
+**Your gain:** routing, implementation, verification, and closeout all move around the same set of facts instead of drifting across free-form summaries.
+
+</td>
+<td width="50%" valign="top">
+<img src="./readme_images/05-feature-icon-compat.svg" width="48" align="left">
+
+**🗂️ Local / Shared Project Storage**
+
+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>/`.
+
+**Your gain:** local runtime isolation stays intact while stable KB and plan assets stop fragmenting across worktrees.
+
 </td>
 </tr>
 </table>
@@ -226,7 +268,7 @@ Codex CLI does not need a manual plugin command. `helloagents --global` now inst
 ```
 💡【HelloAGENTS】- Help
 
-Available commands: ~auto, ~design, ~prd, ~loop, ~init, ~test, ~verify, ~review, ~commit, ~clean, ~help
+Available commands: ~idea, ~auto, ~plan, ~build, ~prd, ~loop, ~wiki, ~init, ~test, ~verify, ~commit, ~clean, ~help
 
 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
 ```
@@ -241,7 +283,7 @@ Auto-activated skills (14): hello-ui, hello-api, hello-security, hello-test, hel
 ~auto "Add user authentication with JWT"
 
 # Want to review the plan first?
-~design "Refactor the payment module"
+~plan "Refactor the payment module"
 ```
 
 ## 🔄 Installation Lifecycle & File Writes
@@ -280,8 +322,10 @@ All commands run inside AI chat with the `~` prefix:
 
 | Command | Purpose |
 |---------|---------|
-| `~auto` | Full autonomous workflow — AI judges complexity, auto-plans and executes |
-| `~design` | Deep interactive design — requirement gathering + solution proposals + plan package |
+| `~idea` | Lightweight ideation — compare directions and explore options without writing files |
+| `~auto` | Automatic orchestration — chooses the right path across ideation / planning / build / verify / PRD, 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 |
 
@@ -290,18 +334,23 @@ All commands run inside AI chat with the `~` prefix:
 | Command | Purpose |
 |---------|---------|
 | `~test` | Write complete tests (TDD: Red → Green → Refactor) |
-| `~verify` | Run all verification commands (lint/test/build/typecheck) |
-| `~review` | Code review with severity classification |
+| `~verify` | Unified verification entry — review, lint, typecheck, test, build, and fix loops |
 
 **Utility Commands:**
 
 | Command | Purpose |
 |---------|---------|
-| `~init` | Initialize project knowledge base (`.helloagents/`) |
+| `~wiki` | Create or sync the project knowledge base only (`.helloagents/`) |
+| `~init` | Full project bootstrap: KB + project-local carrier 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)
+
 ## 🔧 Configuration
 
 Config file: `~/.helloagents/helloagents.json` (auto-created on install)
@@ -316,6 +365,7 @@ Only include keys you want to override — missing keys use defaults.
   "ralph_loop_enabled": true,
   "guard_enabled": true,
   "kb_create_mode": 1,
+  "project_store_mode": "local",
   "commit_attribution": "",
   "install_mode": "standby"
 }
@@ -328,7 +378,8 @@ Only include keys you want to override — missing keys use defaults.
 | `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, `2`=always |
+| `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 artifacts 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 |
 
@@ -355,6 +406,11 @@ helloagents --standby
 { "kb_create_mode": 0 }
 ```
 
+**Share KB and plan packages across multiple worktrees:**
+```json
+{ "project_store_mode": "repo-shared" }
+```
+
 **Enable desktop + sound notifications:**
 ```json
 { "notify_level": 3 }
@@ -369,22 +425,33 @@ helloagents --standby
 
 ## ⚙️ How It Works
 
-**Short version:** HelloAGENTS selects execution depth based on task complexity. Simple tasks run directly; complex tasks use the full 5-stage flow with verification at every step. Once the requirement and execution direction are clear, it prefers direct completion over repeated confirmation.
+**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 routed kernel workflow with explicit ideation, planning, build, verification, and consolidation stages.
 
-**The 5-stage flow:**
+**The routed 6-stage kernel:**
 
-1. **ORIENT** — Read project context (`.helloagents/context.md`, `guidelines.md`, `DESIGN.md`), scan relevant code
-2. **CLARIFY** — Eliminate ambiguity. Simple tasks skip this. Complex tasks confirm key decisions
-3. **PLAN** — Mark which quality skills are needed, generate design/plan if using `~design` or `~prd`
-4. **EXECUTE** — Implement with TDD (test → code → refactor), verify after each step
-5. **VALIDATE** — Run Ralph Loop (lint/test/build), collect delivery checklists from all activated skills, verify each item
+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 artifacts 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 artifacts, and archive completed plan packages
 
-**Routing rules:**
-- Simple tasks (single file, clear fix) → Direct execution
-- Complex tasks (3+ files, architecture change, new project) → Full 5-stage flow via `~design` or `~auto`
+**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 artifacts
+- `T3` — high-risk or irreversible chains such as auth, security, payment, database, or production release work
 
-**Quality skills auto-activate based on task type:**
-- Writing UI code? → `hello-ui` activates (design tokens, accessibility, responsive)
+**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`
+
+**Quality rules and skills by task type:**
+- UI / frontend / visual interaction work always follows the active bootstrap carrier's shared UI kernel
+- 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` evidence
 - Touching API endpoints? → `hello-api` activates (REST conventions, validation, error format)
 - Any code change? → `hello-test`, `hello-verify`, `hello-review` activate
 
@@ -394,10 +461,12 @@ HelloAGENTS supports two installation modes with different installation methods:
 
 | Mode | Install Method | Rules | Skills | Best For |
 |------|---------------|-------|--------|----------|
-| **Standby** (default) | `helloagents install <target> --standby` or `helloagents install --all --standby` | `bootstrap-lite.md` (lite rules) | `~command` on demand, `~init` for full activation | Selective use, keeping other projects unaffected |
+| **Standby** (default) | `helloagents install <target> --standby` or `helloagents install --all --standby` | `bootstrap-lite.md` (lite rules with compact quality floor, shared UI kernel, safety, and completion constraints) | `~command` on demand; before activation, UI tasks still follow the shared UI kernel; 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 |
 
-Standby mode injects rules into `~/.claude/CLAUDE.md`, `~/.gemini/GEMINI.md`, and `~/.codex/AGENTS.md`; Codex then loads that local merged file via `developer_instructions` in `~/.codex/config.toml`. 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`) without plugin hooks.
+Standby mode injects rules into `~/.claude/CLAUDE.md`, `~/.gemini/GEMINI.md`, and `~/.codex/AGENTS.md`; Codex then keeps `developer_instructions` in `~/.codex/config.toml` as the managed fallback so the home `AGENTS.md` remains the primary baseline. During a managed Codex install, HelloAGENTS temporarily removes any existing `model_instructions_file` entry because that setting can shadow the `AGENTS.md` chain; cleanup restores the user's original 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 a synced `~/.codex/AGENTS.md` home baseline, still without plugin hooks.
+
+In standby mode, `.helloagents/` is the activation boundary. Before activation, the lite carrier does **not** run the full 6-stage kernel 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 source of truth.
 
 Bulk switch via CLI: `helloagents --global` or `helloagents --standby`
 
@@ -405,39 +474,45 @@ Re-running the same mode command is also valid. It refreshes the current mode's
 
 ## 📚 Usage Guide
 
-### Three Workflow Modes
+### Core Workflow Lanes
 
 | Mode | Description | When to use |
 |------|-------------|-------------|
-| `~auto` | Full autonomous flow: evaluate → design → develop → verify | Clear requirement, want end-to-end delivery |
-| `~design` | Interactive design only, generates plan package | Want to review the plan before coding |
+| `~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` | Automatic orchestration across the lanes above | Want HelloAGENTS to choose the right path end-to-end |
 | `~prd` | 13-dimension PRD generation | Need comprehensive product requirements |
 
-Typical pattern: `~design` first → review plan → start coding. Or just `~auto` for one-shot delivery.
+Typical pattern: `~idea` first to compare directions, then `~plan` to lock a solution, then `~build`, then `~verify`. Or just `~auto` for one-shot orchestration. 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.
 
 ### Quality Verification (Ralph Loop)
 
 After every task, Ralph Loop auto-runs your project's verification commands:
-- Priority: `.helloagents/verify.yaml` → `package.json` scripts → auto-detected
+- 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 artifacts, or unreplaced template placeholders
 
 ### Knowledge Base (`.helloagents/`)
 
-`~init` creates a project-local knowledge base. `STATE.md` is a project-level recovery snapshot, not a universal memory file for every interaction.
+`~wiki` creates or syncs the project knowledge base only. `~init` is the fuller bootstrap: it also writes project-local carrier files (`AGENTS.md`, `CLAUDE.md`, `.gemini/GEMINI.md`), refreshes the project `skills/helloagents` link, 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-local carrier files are optional.
+
+By default, KB and plan files live in the project's local `.helloagents/`. If `project_store_mode = "repo-shared"`, the local `.helloagents/` directory keeps only the activation signal, `STATE.md`, and runtime artifacts 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.
 
-It is created and continuously updated for long-running project workflows such as `~init`, `~design`, `~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`.
+`STATE.md` is a project-level recovery snapshot, not a universal memory file for every interaction. 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`.
 
 | File | Purpose |
 |------|---------|
-| `STATE.md` | Project-level recovery snapshot (≤50 lines, survives compression) |
-| `DESIGN.md` | Design system (UI projects only) |
+| `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 |
+| `plans/` | Active plan packages (`requirements.md`, `plan.md`, `tasks.md`, `contract.json`) |
 | `archive/` | Completed plan packages |
 
 ### Smart Commit (`~commit`)
@@ -483,7 +558,7 @@ The test suite validates:
 
 **A:** Everything. The v3 line is a complete rewrite:
 - Python package → pure Node.js/Markdown architecture
-- 15 commands → 11 commands + 14 auto-activated quality skills
+- 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.
@@ -499,7 +574,7 @@ The test suite validates:
 <summary><strong>Q: What are the 14 quality skills?</strong></summary>
 
 **A:** They auto-activate based on task type:
-- **hello-ui**: UI construction (design tokens, accessibility, responsive, animation)
+- **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)
@@ -520,13 +595,13 @@ Subagents may skip workflow packaging such as routing, interaction flow, and out
 <details>
 <summary><strong>Q: What is standby vs global mode?</strong></summary>
 
-**A:** Standby mode (default) deploys lite rules to the targets you choose, typically with `helloagents install <target> --standby` or `helloagents install --all --standby`. Projects need `~init` to activate full features. 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`.
+**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>
 
 <details>
 <summary><strong>Q: Where does project knowledge go?</strong></summary>
 
-**A:** In the project-local `.helloagents/` directory. Created by `~init`, auto-synced on code changes (controlled by `kb_create_mode`). `STATE.md` is used as a concise recovery snapshot for long-running workflows, not as a catch-all memory file for every interaction.
+**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 artifacts, 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>
 
 <details>
@@ -589,7 +664,7 @@ Subagents may skip workflow packaging such as routing, interaction flow, and out
 - 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/config.toml` has `model_instructions_file` pointing to `~/.codex/AGENTS.md` in standby mode, or to plugin `AGENTS.md` in global mode
+- Codex CLI: check `~/.codex/AGENTS.md` contains HelloAGENTS markers, `~/.codex/config.toml` still has HelloAGENTS `developer_instructions` and `notify`, and no unexpected `model_instructions_file` is shadowing the managed baseline
 - Restart your CLI
 
 ---
@@ -643,7 +718,32 @@ Subagents may skip workflow packaging such as routing, interaction flow, and out
 
 ## 📈 Version History
 
-### v3.0.2 (current)
+### v3.0.7 (current)
+
+**What the current line now delivers relative to `v2.3.8`:**
+- ✨ Full rewrite from a Python package to a Node.js/Markdown orchestration kernel, including install flow, runtime injection, skill system, and verification chain
+- ✨ Replaced the older layered routing / design-develop model with one routed kernel: 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 artifacts into first-class workflow facts: `STATE.md`, `DESIGN.md`, `requirements.md`, `plan.md`, `tasks.md`, `contract.json`, and `.ralph-*` evidence
+- ✨ 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 assets 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 kernel stays in `bootstrap.md`, while `bootstrap-lite.md` is treated as the standby carrier 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-local carrier files
+- 🔧 Clarified the activation boundary: in standby mode, `.helloagents/` is the actual project activation signal; project-local carrier 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` carriers in standby/global installs
@@ -664,7 +764,7 @@ Subagents may skip workflow packaging such as routing, interaction flow, and out
 
 **Breaking Changes:**
 - 🔴 Complete rewrite: Python package → pure Node.js/Markdown architecture. `pip`/`uv` installation no longer available
-- 🔴 Commands renamed/removed: `~plan` → `~design`, removed `~exec`/`~rollback`/`~rlm`/`~status`/`~validatekb`/`~upgradekb`/`~cleanplan`
+- 🔴 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:**
@@ -676,12 +776,14 @@ Subagents may skip workflow packaging such as routing, interaction flow, and out
 - ✨ `~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`): AI context compression snapshot (≤50 lines)
-- ✨ Design system generation (`DESIGN.md`): auto-created for UI projects
-- ✨ Plan package system: `requirements.md` + `design.md` + `tasks.md`
+- ✨ 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/evidence: only for T3 / UI / high-risk flows, via `contract.json` + `.helloagents/.ralph-advisor.json`
+- ✨ Optional visual validation evidence: only when the UI contract explicitly requires it, via `contract.json` + `.helloagents/.ralph-visual.json`
 
 **Architecture:**
-- 📦 Unified 5-stage execution flow: ORIENT → CLARIFY → PLAN → EXECUTE → VALIDATE
+- 📦 Routed 6-stage kernel: 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)