v2026.5.5 — Cross-Provider Discover-First Parity

Tag: `v2026.5.5` · Released: 2026-05-14 · npm: `npm install -g [email protected]`

Two user-facing changes plus the deployment-pipeline fix that brings the `skill-discovery` rule (the discover-first protocol) to all 10 supported providers on every fresh `aiwg use` invocation. Companion artifact: the Novice-User Adoption study lands as a baselined research deliverable under `.aiwg/studies/novice-user-adoption/`.

TL;DR

# Install
npm install -g [email protected]

# Redeploy AIWG so the now-cross-provider rule reaches your platform
aiwg refresh

# First-time-user safety: try running `aiwg use sdlc` from $HOME
cd ~
aiwg use sdlc          # ← warns about deploy target, 3-second cancellable delay
AIWG_GLOBAL_INSTALL=1 aiwg use sdlc   # ← suppresses warning, deploys silently

If you're a first-time user: `aiwg use` from your home directory or `/tmp` will no longer silently dump 200+ agent files into a place you didn't expect. You get a 3-second warning naming what's about to happen and how to cancel.

If you're a multi-provider user: the discover-first protocol — the rule that mandates `aiwg discover` before declining a request or improvising from training data — now reaches every provider's rules surface. Codex, Copilot, Cursor, Factory, OpenCode, Windsurf, OpenClaw via filesystem deploy; Warp via WARP.md aggregation; Hermes via AGENTS.md priming + MCP `rule-show`. Previously only Claude Code and Cursor had it.

If you're an AIWG contributor: the study under `.aiwg/studies/novice-user-adoption/` documents the discovery audit (Workstream A), read-access audit (E), wizard design + Cognitive Walkthrough (C), engagement-surface design with Lee & See trust calibration (F), 3 empirical-question instruments (G), and the global-install ADR comms drafts (D). The evidence-type taxonomy gains a `deployment-scripted` level between `static-flagged` and `scripted`.

What's in the box

1. Project-isolation warning for `aiwg use`

When you run `aiwg use sdlc` (or any framework) from a directory that has no project signals — no `.git`, `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, `Gemfile`, `build.gradle`, or `*.csproj` up to 3 parent directories — AND your `cwd` is `$HOME`, `/`, or `/tmp`, AIWG now emits:

No project detected here. AIWG will deploy to the current directory. To associate AIWG with a specific project, run this from your project root. Continuing in 3 seconds — press Ctrl-C to cancel.

Three seconds, cancellable with Ctrl-C. Non-cancelled emissions write `warn:no-project-signal` to `.aiwg/activity.log`. The stat-only walk completes in <50ms (CI-enforced via a perf-test gate).

Opt out: `AIWG_GLOBAL_INSTALL=1 aiwg use sdlc` emits a one-line info message ("AIWG_GLOBAL_INSTALL=1 set — deploying to current directory without project check.") and skips the delay.

Source: `src/cli/project-isolation/` (new module). 29 unit tests covering per-signal positive cases, walk-depth boundary (MAX_PARENT_DEPTH = 3), Ctrl-C cancellation, env-var suppression, activity-log integration, performance gate. Module is guarded against the per-framework / per-provider iteration loops so it fires once per CLI process.

Why this matters: novice users who run `aiwg use` from a fresh terminal often land in `$HOME` and don't realize they're deploying 200+ files into a place they'll later have to clean up. The warning surfaces the trade-off at the moment it's most actionable, without breaking the power-user workflow (which is `aiwg use sdlc` from a project root — invisible because project signals are present).

2. Cross-provider discover-first protocol parity

The `skill-discovery` rule encodes the discover-first protocol: before declining a user request as "outside AIWG's scope" or improvising a workflow from training data, the agent MUST run `aiwg discover` against the user's need. Most AIWG skills (~385 of ~400) are not in any provider's loaded context — they reach the agent only via `aiwg discover` + `aiwg show`.

Before this release, the rule was deployed to 2 of 10 providers (Claude Code and Cursor — and even those were stale copies that had drifted from the source-of-truth). After this release: 10 of 10 providers have the rule via their native rule-delivery channel.

Root cause: `agentic/code/addons/aiwg-utils/manifest.json` had `consolidation.deployIndexOnly: true`, which caused `getAddonRuleFiles()` in `tools/agents/providers/base.mjs` to skip the addon's individual rule files. Only the consolidated `RULES-INDEX.md` was deployed; its links pointed at source paths under `$AIWG_ROOT/agentic/code/addons/aiwg-utils/`, which only Claude Code and Cursor could reach reliably.

Fix: `deployIndexOnly` is now `false`. Both the index AND individual rule files deploy together to every provider. Per saved-memory `feedback_parity_no_removal`: always-deploy + adapt — no writer was removed; the deploy set was extended to match the architectural intent.

Provider	Channel
Claude Code	`.claude/rules/skill-discovery.md`
Cursor	`.cursor/rules/skill-discovery.md`
Codex	`.codex/rules/skill-discovery.md`
Copilot	`.github/copilot-rules/skill-discovery.md` + inline section in `.github/copilot-instructions.md`
Factory	`.factory/rules/skill-discovery.md`
OpenCode	`.opencode/rule/skill-discovery.md`
Windsurf	`.windsurf/rules/skill-discovery.md`
OpenClaw	`~/.openclaw/rules/skill-discovery.md`
Warp	inlined into WARP.md aggregation (no `.warp/rules/` channel exists)
Hermes	AGENTS.md priming (Top-7 CRITICAL directives) + on-demand via `mcp_aiwg_rule_show`

Warp aggregation (`tools/warp/setup-warp.mjs`): new `transformRuleToSection()` and `collectAiwgRulePaths()` helpers plus a "## AIWG Rules" aggregation block in `generateAIWGContent()`. skill-discovery sorted first; remaining aiwg-utils rules alphabetical. Regenerated WARP.md jumps from 0 → 101 references to `aiwg discover` / `aiwg show` / `skill-discovery`. The regenerated file is not shipped in this commit (would balloon the diff by ~1.5MB); operators regenerate locally via `node tools/warp/setup-warp.mjs` after `aiwg use sdlc --provider warp`.

Hermes priming (`tools/agents/providers/hermes.mjs`): `CRITICAL_RULE_DIRECTIVES` extended from Top-6 to Top-7. skill-discovery added as the first directive (governs how the agent interacts with AIWG architecturally). ~1KB compressed, well within Hermes's 19KB AGENTS.md hard cap.

3. Scope-model documentation

`docs/cli-reference.md` and `README.md` now document the project-scope (default) vs user-scope (global install) trade-off side-by-side:

• Project scope (recommended): `aiwg use sdlc` from a project root → `./.claude/agents/`, `./.claude/skills/`. One project's agent set never bleeds into another's session.
• User scope (global): `aiwg use sdlc --scope user` → `~/.claude/agents/`, `~/.claude/skills/`. Same set loads into every session. Canonical mode for OpenClaw and Hermes (whose primary discovery is user-scope).

Trade-off cited inline: REF-720 (Lost in Multi-Turn Conversation, MSR/Salesforce 2025) measured a 39% capability drop when context bleeds across unrelated tasks. The new project-isolation warning surfaces this at deploy time.

`ADR-NUA-001` formalizes global install as a first-class supported flow with project-scope as the recommended default. The 5-day Discord/Telegram comms window for the ADR transition is still pending (tracked in #1338 — open by design).

What's NOT in the box

• AIWG.md generator wiring for the new `02b-discover-first.md` template fragment. The fragment is committed and registered in the aiwg-sections manifest. But the current `src/smiths/context-pipeline/aiwg-md.ts` copies CLAUDE.md verbatim and doesn't consume the fragment manifest — that wiring appears to have been orphaned during a prior refactor. Tracked in #1344 (open).
• Field-validated behavioral verification per provider. The deployment is verifiable (rule file appears in the right path); whether each provider's agent actually loads and acts on the rule requires a session per provider. Field-validation sprint is residual work on #1336 (open).
• OpenClaw skills-count anomaly investigation. `~/.openclaw/skills/` deploys only 1 file where other providers deploy 15-20+. Tracked in #1345 (open).

Migration

Nothing to migrate. This is additive across the board. Existing `aiwg use` invocations continue working unchanged. The first time you run `aiwg use` after upgrading, you may see the project-isolation warning if your `cwd` is `$HOME`, `/`, or `/tmp` — that's the new behavior, intentional, and Ctrl-C-cancellable.

If your previous `.claude/rules/skill-discovery.md` or `.cursor/rules/skill-discovery.md` was a stale leftover (md5 different from `agentic/code/addons/aiwg-utils/rules/skill-discovery.md`), the next `aiwg use` overwrites it with current source.

Companion artifact: Novice-User Adoption study

Under `.aiwg/studies/novice-user-adoption/`:

• Workstream A — `hookup-matrix.md` (10-provider × 5-channel matrix; deployment-scripted across all cells; field-validation gap documented)
• Workstream B — `requirements/UC-NUA-002-runs-aiwg-use-first-time.md` + project-isolation code shipped in this release
• Workstream C — `working/wizard-design.md` + `wizard-survey.md` (4-tool pattern survey, full Cognitive Walkthrough record under NFR-USE-02's ≤2-friction-per-step budget)
• Workstream D — `architecture/adr-global-install.md` (PROPOSED) + `working/comms-drafts-adr-global-install.md` + `working/global-install-rough-edges.md` (18-entry per-provider inventory)
• Workstream E — `working/provider-read-audit.md` (CLI-mediated read-access reframing)
• Workstream F — `working/engagement-surface.md` (3-surface design + Lee & See trust calibration + anti-pollution checklist)
• Workstream G — `working/empirical-G{1,2,3}.md` (3 survey/questionnaire instruments + N=1 directional data)

The study introduces `deployment-scripted` as an intermediate evidence type in the SAD §5.2.2 taxonomy: between `static-flagged` (file:line reference only) and `scripted` (CI-verifiable behavior). It captures the layer where on-disk verification confirms the deployment delivers right files to right paths, but doesn't yet verify the agent on the provider reads and acts on them.

CI changes

• New perf-test gate: `test/unit/cli/project-isolation/perf.test.ts` asserts median detection completes in <50ms across 50 iterations (NFR-PERF-01).
• `test/unit/consolidated-rules.test.ts` — 2 tests rewritten to verify the new positive contract (includes aiwg-utils + returns skill-discovery rule). 53/53 pass.
• `.claude-plugin/marketplace.json` `metadata.version` brought back into lockstep with `package.json` (was 2026.5.2; the PUW-038 #1139 check caught the drift on commit 9c054f03 — now 2026.5.5).

Issue activity

Closed in this release: #1335, #1337, #1339, #1340, #1341, #1343, #1346, #1347

Open by design (next-cycle work):

• #1336 — Workstream A hookup audit (partial-pass; field-validation sprint required)
• #1338 — Workstream D global-install ADR (awaiting 5-day comms window)
• #1342 — Citation-validate sweep (dormant)
• #1344 — Inline discover-first protocol into AIWG.md / WARP.md / copilot-instructions.md
• #1345 — Investigate OpenClaw skills-count anomaly

Upgrade

# Stable channel
npm install -g [email protected]
# Or refresh existing install
aiwg refresh
# Verify
aiwg version    # → 2026.5.5
aiwg doctor     # ensure healthy

If you're tracking `next` for pre-release validation, that channel won't move from this release — 2026.5.5 ships as `latest`.

Acknowledgments

The discovery audit that surfaced the cross-provider deployment gap exists because of the `feedback_no_platform_generalization` discipline: static analysis flags candidates, only field reports conclude breakage. The audit upgraded the entire matrix from `static-flagged` to `deployment-scripted` in a single cycle, then surfaced the rule-deployment gap as a concrete actionable finding. Without that discipline, the parity gap would have stayed hypothesized rather than measured.

References

• Parent epic: #1334 (Novice-User Adoption study)
• Commit chain: ac7a2d88 (Workstream B), f6ae3e85 (C/D/E/F/A/G partial deliverables), c32b7e26 (cycle 2 audit), 9c054f03 (cross-provider parity via deployIndexOnly), e49342cc (Warp + Hermes parity completion)
• Saved-memory rules honored: `feedback_parity_no_removal`, `feedback_no_platform_generalization`, `feedback_aiwg_branding_restraint`, `feedback_no_skill_copying`, `feedback_discovery_multi_hook`, `feedback_aiwg_engagement_state`, `feedback_calver_full_versions`
• Research evidence cited: REF-720 (Lost in Multi-Turn Conversation, MSR/Salesforce 2025) for the project-scope cross-bleed trade-off; Lee & See (2004) for the engagement-surface trust-calibration framework