aiwg 2026.5.1 → 2026.5.2

package/CLAUDE.md

@@ -202,7 +202,7 @@ AIWG uses a unified extension system for all extension types:
 
 ## CLI Commands
 
-**See `@docs/cli-reference.md` for complete documentation.** The canonical command list lives in `@src/extensions/commands/definitions.ts` (currently ~85 entries — count grows as features land; the categories table below is a curated overview, not an exhaustive enumeration).
+**See `@docs/cli-reference.md` for complete documentation.** The canonical command list lives in `@src/extensions/commands/definitions.ts` (currently ~94 entries — count grows as features land; the categories table below is a curated overview, not an exhaustive enumeration).
 
 ### Categories
 
@@ -336,8 +336,9 @@ aiwg run skill <name> --cwd <path> -- <args...>   # explicit CWD override
 # $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) + 6 self-maintenance ops (steward, aiwg-doctor,
-# aiwg-refresh, aiwg-status, aiwg-help, use) = 16 skills total.
+# addons + extensions) + 9 self-maintenance ops (steward, aiwg-doctor,
+# aiwg-refresh, aiwg-regenerate, aiwg-status, aiwg-help, aiwg-issue,
+# aiwg-pr, use) = 19 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
@@ -631,6 +632,13 @@ aiwg refresh --channel latest    # switch back to stable
 
 ### Release Checklist
 
+> **Mechanically driven by the `flow-release` skill** as of 2026.5.2.
+> The skill reads `.aiwg/release.config` and walks the declared gates
+> (local build/test → CI green → doc-sync → CHANGELOG + announcement →
+> README freshness → tag/push → post-release tracker close-outs). The
+> checklist below remains the canonical human-readable reference, but
+> `aiwg run skill flow-release` is the recommended path.
+
 Before pushing a version tag:
 
 1. **Update `package.json`** - Bump version following CalVer

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

@@ -7,6 +7,19 @@ platforms: [all]
 
 ---
 
+<!-- AIWG-SKILL-CALLOUT -->
+> **Skill access pattern (post-kernel-pivot, 2026.5+)**
+>
+> Skill names referenced in this document are AIWG skills, **not slash commands**. Most are not kernel-listed and cannot be invoked as `/skill-name` by the platform. Reach them via:
+>
+> ```bash
+> aiwg discover "<capability>"
+> aiwg show skill <name>
+> ```
+>
+> Only kernel-listed skills (`aiwg-doctor`, `aiwg-refresh`, `aiwg-status`, `aiwg-help`, `use`, `steward`) are directly invokable as slash commands. See [skill-discovery rule](../../../addons/aiwg-utils/rules/skill-discovery.md).
+
+
 # Agent Loop Skill
 
 You detect when users want iterative autonomous task execution and route to the appropriate loop command.
@@ -17,7 +30,7 @@ This skill is the **detection and routing layer** for autonomous agent loops —
 
 | Loop Type | Implementation | Description |
 |-----------|---------------|-------------|
-| **Al** | `/ralph` command | Basic iterate-until-complete with learning extraction |
+| **Al** | `ralph` command | Basic iterate-until-complete with learning extraction |
 | *(future)* | — | Reflection loops, critic-actor loops, branching loops |
 
 Currently routes all detected requests to the iterative loop executor. As new loop types are added, this skill will route based on task characteristics.

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

@@ -13,15 +13,28 @@ commandHint:
   platforms: [claude-code, hermes, openclaw]
 ---
 
+<!-- AIWG-SKILL-CALLOUT -->
+> **Skill access pattern (post-kernel-pivot, 2026.5+)**
+>
+> Skill names referenced in this document are AIWG skills, **not slash commands**. Most are not kernel-listed and cannot be invoked as `/skill-name` by the platform. Reach them via:
+>
+> ```bash
+> aiwg discover "<capability>"
+> aiwg show skill <name>
+> ```
+>
+> Only kernel-listed skills (`aiwg-doctor`, `aiwg-refresh`, `aiwg-status`, `aiwg-help`, `use`, `steward`) are directly invokable as slash commands. See [skill-discovery rule](../../../addons/aiwg-utils/rules/skill-discovery.md).
+
+
 # Al External
 
 **You are the Al External Orchestrator** — launching and managing crash-resilient iterative loops that run outside the AI session for long-running tasks.
 
-## Core Difference from `/ralph`
+## Core Difference from `ralph`
 
-`/ralph` runs the loop inside the current AI session. `/agent-loop-ext` (formerly `/ralph-external`) launches the loop as an external process via `tools/ralph-external/run.sh`, persisting all state to `.aiwg/ralph-external/`. If the session dies mid-loop, the loop survives and can be reattached or resumed.
+`ralph` runs the loop inside the current AI session. `agent-loop-ext` (formerly `ralph-external`) launches the loop as an external process via `tools/ralph-external/run.sh`, persisting all state to `.aiwg/ralph-external/`. If the session dies mid-loop, the loop survives and can be reattached or resumed.
 
-Use `/agent-loop-ext` when:
+Use `agent-loop-ext` when:
 - The task will take longer than a single session
 - You need CI/CD pipeline integration
 - You want crash recovery guarantees
@@ -214,11 +227,11 @@ echo "Exit: $?"
 
 ## Related
 
-- `/ralph` — In-session iterative loop (no crash recovery)
-- `/ralph-attach` — Attach to a running external loop's output stream
-- `/ralph-status` — Check active and completed loop status
-- `/ralph-abort` — Stop a running loop
-- `/ralph-resume` — Resume a paused or interrupted loop
+- `ralph` — In-session iterative loop (no crash recovery)
+- `ralph-attach` — Attach to a running external loop's output stream
+- `ralph-status` — Check active and completed loop status
+- `ralph-abort` — Stop a running loop
+- `ralph-resume` — Resume a paused or interrupted loop
 
 ## References
 

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

@@ -11,6 +11,19 @@ commandHint:
   platforms: [claude-code, hermes, openclaw]
 ---
 
+<!-- AIWG-SKILL-CALLOUT -->
+> **Skill access pattern (post-kernel-pivot, 2026.5+)**
+>
+> Skill names referenced in this document are AIWG skills, **not slash commands**. Most are not kernel-listed and cannot be invoked as `/skill-name` by the platform. Reach them via:
+>
+> ```bash
+> aiwg discover "<capability>"
+> aiwg show skill <name>
+> ```
+>
+> Only kernel-listed skills (`aiwg-doctor`, `aiwg-refresh`, `aiwg-status`, `aiwg-help`, `use`, `steward`) are directly invokable as slash commands. See [skill-discovery rule](../../../addons/aiwg-utils/rules/skill-discovery.md).
+
+
 # Al Config
 
 View and modify Al's runtime configuration. Settings control loop behavior defaults such as iteration limits, timeouts, provider selection, and commit behavior. Changes persist to `.aiwg/ralph/config.json` and apply to all subsequent loops unless overridden per-invocation.
@@ -229,8 +242,8 @@ Usage: /ralph-config preset <name>
 
 | Context | Path |
 |---------|------|
-| In-session loops (`/ralph`) | `.aiwg/ralph/config.json` |
-| External loops (`/ralph-external`) | `.aiwg/ralph-external/config.json` |
+| In-session loops (`ralph`) | `.aiwg/ralph/config.json` |
+| External loops (`ralph-external`) | `.aiwg/ralph-external/config.json` |
 
 Each context has its own config file. `show`, `set`, `reset`, and `preset` operate on the in-session config by default. Use `/ralph-config --external show` to inspect external loop config (if the `--external` flag is available in your install).
 
@@ -293,10 +306,10 @@ Check that the .aiwg/ralph/ directory is writable:
 
 ## Related
 
-- `/ralph` — Start an in-session loop (uses this config as defaults)
-- `/ralph-external` — Start a crash-resilient external loop
-- `/ralph-status` — Check active loop state
-- `/ralph-memory` — Manage accumulated loop memory
+- `ralph` — Start an in-session loop (uses this config as defaults)
+- `ralph-external` — Start a crash-resilient external loop
+- `ralph-status` — Check active loop state
+- `ralph-memory` — Manage accumulated loop memory
 
 ## References
 

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

@@ -12,15 +12,28 @@ commandHint:
   platforms: [claude-code, hermes, openclaw]
 ---
 
+<!-- AIWG-SKILL-CALLOUT -->
+> **Skill access pattern (post-kernel-pivot, 2026.5+)**
+>
+> Skill names referenced in this document are AIWG skills, **not slash commands**. Most are not kernel-listed and cannot be invoked as `/skill-name` by the platform. Reach them via:
+>
+> ```bash
+> aiwg discover "<capability>"
+> aiwg show skill <name>
+> ```
+>
+> Only kernel-listed skills (`aiwg-doctor`, `aiwg-refresh`, `aiwg-status`, `aiwg-help`, `use`, `steward`) are directly invokable as slash commands. See [skill-discovery rule](../../../addons/aiwg-utils/rules/skill-discovery.md).
+
+
 # Al External
 
 **You are the Al External Orchestrator** — launching and managing crash-resilient iterative loops that run outside the AI session for long-running tasks.
 
-## Core Difference from `/ralph`
+## Core Difference from `ralph`
 
-`/ralph` runs the loop inside the current AI session. `/ralph-external` launches the loop as an external process via `tools/ralph-external/run.sh`, persisting all state to `.aiwg/ralph-external/`. If the session dies mid-loop, the loop survives and can be reattached or resumed.
+`ralph` runs the loop inside the current AI session. `ralph-external` launches the loop as an external process via `tools/ralph-external/run.sh`, persisting all state to `.aiwg/ralph-external/`. If the session dies mid-loop, the loop survives and can be reattached or resumed.
 
-Use `/ralph-external` when:
+Use `ralph-external` when:
 - The task will take longer than a single session
 - You need CI/CD pipeline integration
 - You want crash recovery guarantees
@@ -209,11 +222,11 @@ echo "Exit: $?"
 
 ## Related
 
-- `/ralph` — In-session iterative loop (no crash recovery)
-- `/ralph-attach` — Attach to a running external loop's output stream
-- `/ralph-status` — Check active and completed loop status
-- `/ralph-abort` — Stop a running loop
-- `/ralph-resume` — Resume a paused or interrupted loop
+- `ralph` — In-session iterative loop (no crash recovery)
+- `ralph-attach` — Attach to a running external loop's output stream
+- `ralph-status` — Check active and completed loop status
+- `ralph-abort` — Stop a running loop
+- `ralph-resume` — Resume a paused or interrupted loop
 
 ## References
 

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

@@ -11,6 +11,19 @@ commandHint:
   platforms: [claude-code, hermes, openclaw]
 ---
 
+<!-- AIWG-SKILL-CALLOUT -->
+> **Skill access pattern (post-kernel-pivot, 2026.5+)**
+>
+> Skill names referenced in this document are AIWG skills, **not slash commands**. Most are not kernel-listed and cannot be invoked as `/skill-name` by the platform. Reach them via:
+>
+> ```bash
+> aiwg discover "<capability>"
+> aiwg show skill <name>
+> ```
+>
+> Only kernel-listed skills (`aiwg-doctor`, `aiwg-refresh`, `aiwg-status`, `aiwg-help`, `use`, `steward`) are directly invokable as slash commands. See [skill-discovery rule](../../../addons/aiwg-utils/rules/skill-discovery.md).
+
+
 # Al Memory
 
 Inspect and manage the semantic memory that Al accumulates across loop iterations. Memory entries record lessons learned, failure patterns, and success patterns so that later iterations — and future loops on similar tasks — benefit from what earlier attempts discovered.
@@ -253,10 +266,10 @@ Usage:
 
 ## Related
 
-- `/ralph` — Loop that generates memory entries
-- `/ralph-external` — External loop with its own memory layer
-- `/ralph-status` — Check loop status and iteration history
-- `/ralph-reflect` — Deeper reflection and memory promotion
+- `ralph` — Loop that generates memory entries
+- `ralph-external` — External loop with its own memory layer
+- `ralph-status` — Check loop status and iteration history
+- `ralph-reflect` — Deeper reflection and memory promotion
 
 ## References
 

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

@@ -11,6 +11,19 @@ commandHint:
   orchestration: true
 ---
 
+<!-- AIWG-SKILL-CALLOUT -->
+> **Skill access pattern (post-kernel-pivot, 2026.5+)**
+>
+> Skill names referenced in this document are AIWG skills, **not slash commands**. Most are not kernel-listed and cannot be invoked as `/skill-name` by the platform. Reach them via:
+>
+> ```bash
+> aiwg discover "<capability>"
+> aiwg show skill <name>
+> ```
+>
+> Only kernel-listed skills (`aiwg-doctor`, `aiwg-refresh`, `aiwg-status`, `aiwg-help`, `use`, `steward`) are directly invokable as slash commands. See [skill-discovery rule](../../../addons/aiwg-utils/rules/skill-discovery.md).
+
+
 # Al Resume
 
 Resume a paused or interrupted agent loop.
@@ -82,7 +95,7 @@ Continuing from iteration {N+1}...
 
 ### Step 4: Handle Completion
 
-Same as `/ralph` - generate completion report on success or limit.
+Same as `ralph` - generate completion report on success or limit.
 
 ## Resume Context
 
@@ -169,9 +182,9 @@ Continues from last checkpoint with original settings.
 
 ## Related
 
-- `/ralph-status` - Check what state the loop is in
-- `/ralph-abort` - Stop instead of resume
-- `/ralph` - Start new loop
+- `ralph-status` - Check what state the loop is in
+- `ralph-abort` - Stop instead of resume
+- `ralph` - Start new loop
 
 ## References
 

package/agentic/code/addons/aiwg-dev/skills/devkit-create-command/SKILL.md

@@ -5,6 +5,19 @@ platforms: [all]
 description: Create a new slash command with AI-guided behavior definition
 ---
 
+<!-- AIWG-SKILL-CALLOUT -->
+> **Skill access pattern (post-kernel-pivot, 2026.5+)**
+>
+> Skill names referenced in this document are AIWG skills, **not slash commands**. Most are not kernel-listed and cannot be invoked as `/skill-name` by the platform. Reach them via:
+>
+> ```bash
+> aiwg discover "<capability>"
+> aiwg show skill <name>
+> ```
+>
+> Only kernel-listed skills (`aiwg-doctor`, `aiwg-refresh`, `aiwg-status`, `aiwg-help`, `use`, `steward`) are directly invokable as slash commands. See [skill-discovery rule](../../../addons/aiwg-utils/rules/skill-discovery.md).
+
+
 # Create AIWG Command
 
 Create a new slash command with AI assistance to define arguments, behavior, and output.
@@ -39,17 +52,17 @@ Create a new slash command with AI assistance to define arguments, behavior, and
 ### utility (default)
 Simple operation, single action command.
 - Best for: Quick tasks, file operations, status checks
-- Example: `/lint-check`, `/deploy-status`
+- Example: `lint-check`, `deploy-status`
 
 ### transformation
 Content/code transformation pipeline with input/output handling.
 - Best for: Format conversion, code refactoring, content processing
-- Example: `/convert-format`, `/refactor-code`
+- Example: `convert-format`, `refactor-code`
 
 ### orchestration
 Multi-agent workflow coordination with phases and parallel execution.
 - Best for: Complex workflows, phase transitions, multi-step processes
-- Example: `/flow-deploy-to-production`, `/flow-security-review`
+- Example: `flow-deploy-to-production`, `flow-security-review`
 
 ## Interactive Mode
 
@@ -127,9 +140,9 @@ aiwg add-command <name> --to <target> --template <type>
 
 ## Related Commands
 
-- `/devkit-create-agent` - Create an agent
-- `/devkit-create-skill` - Create an auto-triggered skill
-- `/devkit-validate` - Validate command structure
+- `devkit-create-agent` - Create an agent
+- `devkit-create-skill` - Create an auto-triggered skill
+- `devkit-validate` - Validate command structure
 
 ## References
 

package/agentic/code/addons/aiwg-utils/skills/aiwg-issue/SKILL.md

@@ -0,0 +1,169 @@
+---
+namespace: aiwg
+name: aiwg-issue
+platforms: [all]
+kernel: true
+description: Guide for filing high-quality issues — template selection, environment capture, duplicate detection, and import flow for cross-tracker reports
+---
+
+# Filing AIWG Issues
+
+You are helping a user (or yourself, as an autonomous agent) file a high-quality issue. The bar is set by the recent tester-report import sweep (Gitea #1264–#1269): environment captured, exact commands, error text in code blocks, suggested fix paths.
+
+## When this fires
+
+Natural-language triggers:
+
+- "I want to file an issue"
+- "How do I report a bug?"
+- "Help me write up a bug report"
+- "What template should I use?"
+- "Should I file a new issue or comment on an existing one?"
+- "Import this report from GitHub" / "from Discord" / "from email"
+
+## Template selection
+
+| Template | When to use | Path |
+|---|---|---|
+| `bug-report.md` | One concrete defect with a reproduction | `.gitea/ISSUE_TEMPLATE/bug-report.md` |
+| `feature-request.md` | A new capability or enhancement proposal | `.gitea/ISSUE_TEMPLATE/feature-request.md` |
+| `tester-report.md` | A single session that surfaced multiple findings | `.gitea/ISSUE_TEMPLATE/tester-report.md` |
+| `imported-report.md` | Mirroring an issue filed in a different tracker | `.gitea/ISSUE_TEMPLATE/imported-report.md` |
+
+Templates exist in both `.gitea/ISSUE_TEMPLATE/` (for Gitea) and `.github/ISSUE_TEMPLATE/` (for the GitHub mirror). Pick the one matching the target tracker; the content is identical.
+
+## The walkthrough
+
+### 1. Triage first
+
+Ask: is this one bug, or multiple findings from a single session?
+
+- **One issue** → `bug-report.md` or `feature-request.md`
+- **Multiple findings** → `tester-report.md`, split into discrete bugs during follow-up triage
+- **Already filed elsewhere** → `imported-report.md`
+
+**One bug per issue.** If three things broke, file three issues (or one tester-report and split). Don't bundle.
+
+### 2. Duplicate detection (BEFORE filing)
+
+Always check for duplicates first. Cheaper to comment on an existing thread than file again. Use:
+
+```bash
+aiwg discover "<keywords from the proposed title>"
+```
+
+Then search the tracker for matching titles. The `steward-prep-delivery` skill bundles both lookups into one command:
+
+```bash
+aiwg run skill steward-prep-delivery -- "<search terms>"
+```
+
+If a likely duplicate exists, comment on it rather than filing fresh.
+
+### 3. Environment capture (bug reports)
+
+Bug reports without environment context get bounced. Collect:
+
+```bash
+aiwg version           # AIWG version + channel
+aiwg doctor            # workspace health snapshot
+node --version
+uname -a               # OS / kernel
+```
+
+Capture the **platform** explicitly: Claude Code, hermes, Codex, Copilot, Cursor, Warp, Factory, OpenCode, Windsurf, OpenClaw. The same bug behaves differently across providers. The tester report imports in May 2026 (#1264–#1268) had to correct the platform from "Claude Code" to "hermes-agent" after the fact — get it right the first time.
+
+### 4. Reproducible repro
+
+Paste **exact** commands (copy-paste-ready, no `<placeholder>`s without explicit substitution instructions) and **exact** error text in fenced code blocks. Paraphrased errors lose detail.
+
+Bad:
+> "When I run the steward command it errors out"
+
+Good:
+> ```
+> $ aiwg steward capabilities --provider claude-code
+> ERROR ENOENT: no such file or directory, open '/home/linuxbrew/.linuxbrew/lib/node_modules/aiwg/dist/agentic/code/providers/capability-matrix.yaml'
+> ```
+
+### 5. Title format
+
+`type(scope): one-line summary`. Examples:
+
+- `bug(steward): AIWG_ROOT path resolution lands at dist/ instead of package root`
+- `feat(contributing): consistent PR + Issue templates`
+- `regression: Skill Seekers implementation lost`
+- `imported: <original title> (<source>#<number>)` for imports
+
+Vague titles ("doesn't work", "broken") get bumped back. Insist on the typed form.
+
+### 6. Suggested fix (if you've investigated)
+
+If you've already traced the bug, point at the file or line. "I think this is in `src/cli/handlers/steward.ts:26`" is faster than a round-trip. This is optional but valued — the recent #1261/#1262/#1263 imports landed faster because the original reporter included file-line pointers.
+
+### 7. Acceptance criteria
+
+Bug reports should include checkable acceptance:
+
+```markdown
+- [ ] Repro from "Steps to reproduce" no longer fails
+- [ ] Regression test added (if the bug bypassed existing tests)
+- [ ] Related docs updated (if behavior was documented incorrectly)
+```
+
+Feature requests need concrete, checkable conditions — not "works well" or "feels right".
+
+## Import flow (cross-tracker reports)
+
+When a report lands in a different tracker (GitHub mirror, Discord, email, vendor support), mirror to Gitea as `imported-report.md`:
+
+1. Title: `imported: <original title> (<source>#<number>)`
+2. Link the source URL
+3. Preserve the **original reporter handle** and **platform/environment** (correct it if the source got it wrong)
+4. Add a "Status against current main" table
+5. Cross-reference any local issues that duplicate or overlap
+6. If already fixed: note the resolving commit and close as duplicate
+7. **Thank the original reporter** in a closing comment when the work lands
+
+Example: jmagly#108–#112 → roctinam #1264–#1268 sweep (May 2026).
+
+## Filing
+
+```bash
+aiwg run skill issue-create -- "<title>" --provider gitea --labels "bug"
+```
+
+Or use the tracker's web UI with the template. Both are valid.
+
+For Gitea via MCP (if available):
+
+```yaml
+mcp__git-gitea__issue_write:
+  method: create
+  owner: roctinam
+  repo: aiwg
+  title: '<title>'
+  body: '<full body following bug-report.md template>'
+```
+
+## After filing
+
+- Add labels (priority, area, type) per the `ops-issue-tracking` rule conventions
+- Link related issues with `Refs #N` / `Blocked-by: #N` / `Blocks: #N` in the body
+- Watch the thread for triage comments and answer promptly
+
+## Anti-patterns to flag
+
+- **"While I'm at it"** — adding unrelated changes to a bug report. Split into separate issues.
+- **Bundling fixes into the report** — if you have a fix, file the issue first, then submit the PR with `Closes #N`. Don't mix.
+- **Re-filing duplicates** — always run duplicate detection first.
+- **Vague titles** — `type(scope): subject` form is required.
+- **Missing environment** — bug reports without OS/version/platform get clarified before action.
+
+## Related
+
+- Skills: `aiwg-pr` (filing PRs), `steward-prep-delivery` (interactive walkthrough), `issue-create` (low-level filing), `issue-auto-sync` (commit↔issue linking)
+- Templates: `.gitea/ISSUE_TEMPLATE/`, `.github/ISSUE_TEMPLATE/`
+- Docs: `CONTRIBUTING.md` (full contributor guide)
+- Rules: `delivery-policy`, `no-attribution`, `ops-issue-tracking`
+- Origin: #1269 (templates), #1264–#1268 (tester report sweep that motivated this)