aiwg 2026.5.13 → 2026.6.1

package/CLAUDE.md

@@ -34,7 +34,7 @@ agentic/code/
 │   ├── knowledge-base/       # Knowledge base / wiki framework
 │   └── ops-complete/         # Operational infrastructure (incident, runbooks, troubleshooting)
 ├── addons/
-│   └── voice-framework/     # Voice profiles (one of 27 addons)
+│   └── voice-framework/     # Voice profiles (one of 29 addons)
 └── agents/                  # Writing quality agents
 
 src/                         # CLI and MCP server implementation
@@ -79,7 +79,7 @@ All 10 providers receive all 4 artifact types (agents, commands, skills, rules).
 | Platform | Agents | Commands | Skills | Rules | Command |
 |----------|--------|----------|--------|-------|---------|
 | Claude Code | `.claude/agents/` | `.claude/commands/` | `.claude/skills/` | `.claude/rules/` | `aiwg use sdlc` |
-| OpenAI/Codex | `.codex/agents/` | `~/.codex/prompts/` (scanned) + `.codex/commands/` (deployed for visibility; not scanned — Codex commands are a static enum) | `~/.codex/skills/` + `.agents/skills/` | `.codex/rules/` | `aiwg use sdlc --provider codex` |
+| OpenAI/Codex | `.codex/agents/` | `~/.codex/prompts/` (scanned) + `.codex/commands/` (deployed for visibility; not scanned — Codex commands are a static enum) | `.agents/skills/` (project) + `~/.agents/skills/` (user) | `.codex/rules/` | `aiwg use sdlc --provider codex` |
 | GitHub Copilot | `.github/agents/` | `.github/prompts/` | `.github/skills/` + `.agents/skills/` | `.github/instructions/` | `aiwg use sdlc --provider copilot` |
 | Factory AI | `.factory/droids/` | `.factory/commands/` | `.factory/skills/` | `.factory/rules/` | `aiwg use sdlc --provider factory` |
 | Cursor | `.cursor/agents/` | `.cursor/commands/` | `.cursor/skills/` | `.cursor/rules/` | `aiwg use sdlc --provider cursor` |
@@ -87,16 +87,18 @@ All 10 providers receive all 4 artifact types (agents, commands, skills, rules).
 | Warp Terminal | `.warp/agents/` + WARP.md | `.warp/commands/` | `.warp/skills/` + `.agents/skills/` | `.warp/rules/` | `aiwg use sdlc --provider warp` |
 | Windsurf | AGENTS.md | `.windsurf/workflows/` | `.windsurf/skills/` + `.agents/skills/` | `.windsurf/rules/` | `aiwg use sdlc --provider windsurf` |
 | OpenClaw | `~/.openclaw/agents/` | `~/.openclaw/commands/` | `~/.openclaw/skills/` + `.agents/skills/` | `~/.openclaw/rules/` | `aiwg use sdlc --provider openclaw` |
-| Hermes | AGENTS.md + .hermes.md | via MCP `command-run` | `~/.hermes/skills/` (kernel) + `~/.hermes/skills/.aiwg/` (standard) | inlined in AGENTS.md + MCP `rule-list`/`rule-show` | `aiwg use sdlc --provider hermes` |
+| Hermes | AGENTS.md + .hermes.md | AGENTS.md bridge + `aiwg discover`/`show` (MCP `command-run` optional) | `~/.hermes/skills/` (kernel) + `~/.hermes/skills/.aiwg/` (standard) | AGENTS.md `### Rule:` sections + `aiwg show rule` (MCP `rule-list`/`rule-show` optional) | `aiwg use sdlc --provider hermes` |
+| OpenHuman | `.agents/agents/` | AGENTS.md bridge | `~/.openhuman/skills/` (kernel, global) + `~/.openhuman/.aiwg/skills/` (standard) | AGENTS.md `### Rule:` sections + `aiwg show rule` | `aiwg use sdlc --provider openhuman` |
 | Omnius (bundled, first-party integrator) | bundled in Omnius runtime | bundled in Omnius runtime | bundled in Omnius runtime | bundled in Omnius runtime | `npm i -g omnius` |
 
 **Special cases:**
-- **Codex**: Commands and skills deploy to home directory (`~/.codex/prompts/`, `~/.codex/skills/`) for user-level availability across all projects. `.codex/commands/` also deploys at project scope for operator visibility, but Codex commands are a static built-in enum in codex-rs and these files are not auto-scanned by the loader; AGENTS.md is the discovery bridge per ADR-1. Reference: `src/smiths/platform-paths.ts:23`.
+- **Codex**: Commands deploy to the home directory (`~/.codex/prompts/`) for user-level availability across all projects. Skills deploy to the cross-provider `.agents/skills/` (project scope) or `~/.agents/skills/` (user scope) — the paths codex-rs natively scans (`codex-rs/core-skills/src/loader.rs`). The legacy `~/.codex/skills/` home dir is deprecated and pruned on deploy: writing both it and `.agents/skills/` made codex list every kernel skill twice (`/aiwg-regenerate` etc.), since codex-rs scans both. `.codex/commands/` also deploys at project scope for operator visibility, but Codex commands are a static built-in enum in codex-rs and these files are not auto-scanned by the loader; AGENTS.md is the discovery bridge per ADR-1. Reference: `src/smiths/platform-paths.ts:23`.
 - **Copilot**: Agents use `.agent.md` format (Markdown + YAML frontmatter). Commands deploy as prompt files (`.github/prompts/`). Rules deploy as path-scoped instructions (`.github/instructions/`)
 - **Warp**: Agents and commands are also aggregated into `WARP.md` for single-file context loading
 - **Windsurf**: Agents are aggregated into `AGENTS.md` at project root
 - **OpenClaw**: All artifacts deploy to home directory (`~/.openclaw/`). First provider to support behaviors (`~/.openclaw/behaviors/`)
-- **Hermes**: MCP sidecar architecture (`Hermes → MCP → AIWG`). Commands reach AIWG via `mcp_aiwg_command_run` (allow-listed). Standard skills (~385) live under `~/.hermes/skills/.aiwg/` and are recursively discovered; kernel skills (~9) live at the top level and are protected from the Curator (v0.12.0+) via the `.bundled_manifest`. The MCP server has ~12 core tools by default; ~45 additional via `AIWG_MCP_TOOLSETS=<csv>`. See `docs/integrations/hermes-quickstart.md`.
+- **Hermes**: Integrates like Claude Code and Codex — file-based deploy + `aiwg discover`/`aiwg show` CLI + AGENTS.md/.hermes.md bridge (Discover-First Protocol). **MCP is optional**: AIWG's MCP server is a global hook any provider may use, but Hermes does not require it (validated v2026.5.13, #1527). When MCP is enabled, commands reach AIWG via `mcp_aiwg_command_run` (allow-listed) and the server exposes 16 core tools by default (45 more via `AIWG_MCP_TOOLSETS=<csv>`). Standard skills (~460) live under `~/.hermes/skills/.aiwg/` (recursively discovered) and are also reachable through the capability index without file deploy; kernel skills (~20) live at the top level, protected from the Curator (v0.12.0+) via the `.bundled_manifest`. Rules are inlined into AGENTS.md as compressed `### Rule:` directives, with full bodies reachable through `aiwg show rule <name>` even when MCP is disabled. Broader MCP modernization is tracked in #1533. See `docs/integrations/hermes-quickstart.md`.
+- **OpenHuman** (tinyhumansai): OSS personal-AI runtime (Rust core + Tauri desktop), AIWG-convention-aware out of the box — ships `.agents/`, `AGENTS.md`, `.claude/`, `.codex/`. Kernel skills install **globally like OpenClaw** to `~/.openhuman/skills/` (ungated user-scope native scan via `ops_discover.rs`, one-level — exactly what the app's Skills library surfaces), standard skills sequestered under `~/.openhuman/.aiwg/skills/` for index-driven discovery. Markdown personas stay **workspace-scoped** at `.agents/agents/` (consumed by the coding hosts OpenHuman drives — `claude_code`/`factory`), and commands/rules aggregate into the workspace `AGENTS.md` bridge. The project-scope trust marker is no longer written — user-scope is ungated (#1553). The native agent harness (TOML specialists) is an opt-in Tier-2 surface (#1559). Induction epic #1552; see `docs/integrations/openhuman-quickstart.md` (#1558).
 - **Omnius** (first-party integrator): Ships AIWG embedded inside the Omnius autonomous coding agent runtime — no separate `aiwg use` step required. `npm i -g omnius` installs both. AIWG skills, agents, and rules are reachable through `aiwg discover` from inside Omnius sessions and through Omnius's REST (`/v1/aiwg/*`) and MCP bridges. Treat Omnius like any AIWG-aware host: the `skill-discovery`, `delivery-policy`, `human-authorization`, and `anti-laziness` rules all apply unchanged. See https://www.npmjs.com/package/omnius.
 
 ## Writing Principles
@@ -335,13 +337,13 @@ aiwg run skill <name> --cwd <path> -- <args...>   # explicit CWD override
 # `"executable": true` with a `run_hint`; `aiwg show` prepends a one-line
 # banner so agents know to use this command instead of running raw paths.
 
-# Most AIWG skills (~385 of 400) are NOT in your context — they stay at
+# Most AIWG skills (~460 of 480) are NOT in your context — they stay at
 # $AIWG_ROOT (no per-project copy by default, #1217) and are reached via
 # `aiwg discover` + `aiwg show`. The kernel set is what's always-loaded:
 # 8 framework quickrefs + aiwg-utils-quickref + aiwg-language-map (covers
-# addons + extensions) + 9 self-maintenance ops (steward, aiwg-doctor,
+# addons + extensions) + 10 self-maintenance ops (steward, aiwg-doctor,
 # aiwg-refresh, aiwg-regenerate, aiwg-status, aiwg-help, aiwg-issue,
-# aiwg-pr, use) = 19 skills total.
+# aiwg-pr, aiwg-mission, use) = 20 skills total.
 # The skill-discovery HIGH rule mandates `aiwg discover` before declining
 # a user request as out-of-scope.
 # To force per-project copies (sandboxed runtimes): pass --copy-all
@@ -681,3 +683,18 @@ Before pushing a version tag:
 - PATCH resets each month
 - Tag format: `vYYYY.M.PATCH` (e.g., `v2026.1.5`)
 - See `@docs/contributing/versioning.md` for full details
+
+<!-- AIWG:claude-md-hook:start -->
+
+# AIWG
+
+@AIWG.md
+
+<!--
+  This block is managed by `aiwg regenerate` and `aiwg use`.
+  Operator content above and below this block is preserved on regenerate.
+  To change AIWG.md content, edit .aiwg/AIWG.md (the normalized source)
+  then run `aiwg regenerate`.
+-->
+
+<!-- AIWG:claude-md-hook:end -->

package/README.md

@@ -1,5 +1,7 @@
 <div align="center">
 
+<a href="https://aiwg.io"><img src="https://aiwg.io/assets/badges/aiwg-hero-dark.png" alt="AIWG — multi-agent AI framework · one source of truth · 10 platforms" width="680"></a>
+
 # AIWG
 
 **Multi-agent AI framework for Claude Code, Copilot, Cursor, Warp, and 6 more platforms**
@@ -11,6 +13,9 @@ npm i -g aiwg        # install globally
 aiwg use sdlc        # deploy SDLC framework
 ```
 
+macOS users: if npm fails with `EACCES` under `/usr/local/lib/node_modules`,
+use the [macOS Install Guide](docs/getting-started/macos-install.md).
+
 [![npm version](https://img.shields.io/npm/v/aiwg/latest?label=npm&color=CB3837&logo=npm&style=flat-square)](https://www.npmjs.com/package/aiwg)
 [![npm downloads](https://img.shields.io/npm/dm/aiwg?color=CB3837&logo=npm&style=flat-square)](https://www.npmjs.com/package/aiwg)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
@@ -19,7 +24,9 @@ aiwg use sdlc        # deploy SDLC framework
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org)
 [![10 Platforms](https://img.shields.io/badge/Platforms-10-purple?style=flat-square)](#-platform-support)
 
-[**Get Started**](#quick-start) · [**Features**](#what-you-get) · [**Agents**](#agents) · [**CLI Reference**](docs/cli-reference.md) · [**Documentation**](#documentation) · [**Community**](#community--support)
+[![Built With AIWG](https://aiwg.io/assets/badges/built-with-aiwg-dark.png)](https://aiwg.io/badges)
+
+[**Get Started**](#quick-start) · [**Features**](#what-you-get) · [**Agents**](#agents) · [**CLI Reference**](docs/cli-reference.md) · [**Documentation**](#documentation) · [**Community**](#community--support) · [**Badges**](https://aiwg.io/badges)
 
 [![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/BuAusFMxdA)
 [![Telegram](https://img.shields.io/badge/Telegram-Join-26A5E4?logo=telegram&logoColor=white&style=flat-square)](https://t.me/+oJg9w2lE6A5lOGFh)
@@ -30,6 +37,34 @@ aiwg use sdlc        # deploy SDLC framework
 
 ## Installation Troubleshooting
 
+### macOS npm `EACCES`
+
+If `npm install -g aiwg` fails with `EACCES` while writing to
+`/usr/local/lib/node_modules/aiwg`, npm is using a system-owned global install
+directory. The recommended Mac path is Node 24 through `nvm`, then:
+
+```bash
+npm install -g aiwg
+aiwg --version
+```
+
+If Node is already installed and you need a quick recovery, use npm's current
+user-owned prefix guidance:
+
+```bash
+npm config set prefix ~/.local
+echo 'PATH="$HOME/.local/bin:$PATH"' >> ~/.profile
+echo 'source ~/.profile' >> ~/.zprofile
+source ~/.profile
+npm install -g aiwg
+```
+
+See [macOS Install Guide](docs/getting-started/macos-install.md) for the full
+walkthrough. Avoid `sudo npm install -g aiwg` as the default fix; it can create
+root-owned npm files that break later upgrades.
+
+### `aiwg` command not found
+
 If `aiwg` is not found after `npm i -g aiwg`, the npm global `bin` directory is not on your `PATH`. Confirm and fix:
 
 ```bash
@@ -1501,7 +1536,7 @@ Research foundation: Recursive Language Models (Zhang, Kraska, Khattab — MIT C
 
 ## Research Foundations
 
-AIWG's architecture is grounded in peer-reviewed research across cognitive science, multi-agent systems, software engineering, and AI safety. Full corpus: [research-papers](https://github.com/jmagly/research-papers) (168 papers). Entries ordered highest to lowest GRADE evidence quality within each category.
+AIWG's architecture is grounded in peer-reviewed research across cognitive science, multi-agent systems, software engineering, and AI safety. Reference summaries live in `docs/references/` (REF-NNN entries), ordered highest to lowest GRADE evidence quality within each category.
 
 ### Cognitive Foundations
 
@@ -1816,6 +1851,20 @@ We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ---
 
+## Badges
+
+Building on AIWG? Show it. Grab a **Built With AIWG** / **Powered By AIWG** badge — light and dark, hosted and free to hot-link (no need to copy the image into your repo):
+
+[![Built With AIWG](https://aiwg.io/assets/badges/built-with-aiwg-dark.png)](https://aiwg.io)
+
+```md
+[![Built With AIWG](https://aiwg.io/assets/badges/built-with-aiwg-dark.png)](https://aiwg.io)
+```
+
+Full set with copy-paste snippets at **[aiwg.io/badges](https://aiwg.io/badges)**.
+
+---
+
 ## Usage Notes
 
 AIWG is optimized for token efficiency. Rules deploy as a consolidated index (~200 lines) instead of 35 individual files (~9,321 lines). Most users on **Claude Pro** or similar plans will have no issues. See [Usage Notes](docs/usage-notes.md) for rate limit guidance.

package/agentic/code/addons/agent-loop/skills/agent-loop/SKILL.md

@@ -46,8 +46,9 @@ Before choosing the loop mechanism, detect the active provider via `aiwg runtime
 | Provider capability | Route | Notes |
 |---|---|---|
 | Provider with native `/goal` (Codex, Claude Code) | Delegate the in-session loop to `/goal` | Convert the task plus completion criterion into a standing goal. If a programmatic goal tool is unavailable, print the exact `/goal "..."` command for the operator instead of emulating a duplicate loop. |
+| Provider with native dynamic orchestration (Claude Code Workflow tool) | In-session multi-agent fan-out MAY delegate to the native orchestration tool | AIWG retains audit, gates, best-output selection, and cross-session durability. The native tool is in-session/background scoped — NOT a detached daemon — so detached/resume-after-session work stays AIWG-native (see external row). |
 | Other providers | AIWG internal loop discipline | Keep the existing visible act/verify/adapt cycle in the current session. |
-| Explicit external/background request | `agent-loop-ext` / `ralph-external` | External crash-resilient loops stay AIWG-native because `/goal` is in-session only. |
+| Explicit external/background request | `agent-loop-ext` / `ralph-external` | Detached, crash-resilient, resume-after-session-ends work stays AIWG-native: `/goal` is in-session, and the Claude Code Workflow tool is session-scoped. Codex has no core `/workflow` (verified, `codex-cli 0.135.0`, #1535). |
 
 Native `/goal` mapping:
 
@@ -59,6 +60,8 @@ When completion is omitted, run `infer-completion-criteria` first and include th
 
 Research and decision record: `.aiwg/research/codex-goal-integration.md`, `.aiwg/architecture/adr-codex-goal-routing.md`. The Claude Code dialect is the same operator-facing form: `/goal "<task>; completion: <criterion>"`.
 
+External/orchestration routing (provider-native `/workflow`): `.aiwg/research/provider-workflow-integration.md`, `.aiwg/architecture/adr-workflow-routing.md`. Verified against `codex-cli 0.135.0` (#1535): Codex has no core `/workflow`; Claude Code's Workflow tool is the in-session orchestration analog. Detached/cross-session work stays AIWG-native (`ralph-external`).
+
 ### Default: Internal/In-Session Loop
 
 Use the internal loop when the user says `agent-loop`, `al`, `ralph`, `loop`, `iterate`, `keep trying`, `fix until green`, `address issues`, `handle all listed issues`, or supplies an iteration bound such as `--iterations 200` without explicit external wording.