aiwg 2026.5.12 → 2026.6.0

package/CLAUDE.md

@@ -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 (~385) live under `~/.hermes/skills/.aiwg/` (recursively discovered) and are also reachable through the capability index without file deploy; kernel skills (~9) 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
@@ -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

@@ -11,6 +11,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)
@@ -30,6 +33,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 +1532,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
 

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.

package/agentic/code/addons/aiwg-utils/agents/aiwg-steward.md

@@ -325,6 +325,21 @@ When a user asks "what command should I use for X?", follow this protocol:
 | "I want to use behaviors" | claude-code | AIWG emulation — `aiwg add-behavior` + daemon; Claude Code has hooks but not full behaviors |
 | "Does Cursor support MCP?" | cursor | Yes — native MCP support. Configure with `aiwg mcp install cursor` |
 
+### Orchestration & loop routing
+
+For "iterate until done" / multi-agent orchestration / Mission requests, the canonical routing surface is the **agent-loop Step 0 table** (`agentic/code/addons/agent-loop/skills/agent-loop/SKILL.md`), backed by `.aiwg/architecture/adr-workflow-routing.md`. Summary:
+
+| User Request | Provider | Correct Answer |
+|-------------|----------|----------------|
+| "iterate on this until tests pass" (in-session) | claude-code / codex | Native `/goal "<task>; completion: <criterion>"` (#1451/#1469) — in-session loop |
+| "fan out multiple agents in-session" | claude-code | MAY delegate the mechanism to the native Workflow tool; AIWG retains audit/gates/best-output/durability |
+| "fan out multiple agents in-session" | codex | No core `/workflow` (it's plugin-provided, #1535); use the AIWG-owned `/aiwg-mission` or `aiwg mc dispatch` |
+| "launch a Mission" / dynamic orchestration | any | `/aiwg-mission` (Codex) or `aiwg mc dispatch`; AIWG-owned durable conductor |
+| "run detached/background/crash-resilient" | any | AIWG-native external route (`agent-loop-ext` / `ralph-external`) — native primitives are session-scoped |
+| "coordinate Codex AND Claude agents" (cross-stack) | any | Cross-stack Mission (#1546) — one AIWG conductor dispatches workers to executors advertising the target `runtime:<name>` (e.g. `runtime:codex`) via the `serve` registry (routeMission) |
+
+**Invariant:** whatever drives the worker mechanism, AIWG owns activity-log, gates, best-output selection, checkpoint/resume durability, reproducibility, and cost. Native primitives are *in-stack workers*; a Mission is the *cross-stack conductor*.
+
 ## Cross-Provider Diagnostic
 
 When asked to diagnose capability gaps (e.g., "how does my setup compare to Claude Code?"):

package/agentic/code/addons/aiwg-utils/manifest.json

@@ -31,7 +31,30 @@
     "rules": "rules/",
     "skills": "skills/",
     "templates": "templates/",
-    "prompts": "prompts/"
+    "prompts": "prompts/",
+    "workflow": "workflow/"
+  },
+  "workflow": {
+    "description": "Core AIWG workflow metalanguage (apiVersion: workflow.aiwg.io/v1) — declarative spec for capabilities, playbooks, inventories, targets, gates, roles, and extensions. Lifted from ops-complete to a core primitive so any framework can author workflows.",
+    "schemas": "workflow/schemas/",
+    "docs": "workflow/docs/",
+    "examples": "workflow/examples/",
+    "kinds": [
+      "WorkflowCapability",
+      "WorkflowPlaybook",
+      "WorkflowInventory",
+      "WorkflowTarget",
+      "WorkflowGate",
+      "WorkflowRole",
+      "WorkflowExtension"
+    ],
+    "legacy_apiversion_aliases": {
+      "ops.aiwg.io/v1": "workflow.aiwg.io/v1",
+      "sys.ops.aiwg.io/v1": "sys.workflow.aiwg.io/v1",
+      "it.ops.aiwg.io/v1": "it.workflow.aiwg.io/v1",
+      "dev.ops.aiwg.io/v1": "dev.workflow.aiwg.io/v1",
+      "stream.ops.aiwg.io/v1": "stream.workflow.aiwg.io/v1"
+    }
   },
   "consolidation": {
     "strategy": "index-with-links",

package/agentic/code/addons/aiwg-utils/rules/auto-compact-continue.md

@@ -246,8 +246,8 @@ If none of those apply: **continue**.
 - @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/context-budget.md — Aggressive budgeting when `AIWG_CONTEXT_WINDOW` is set
 - @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/skill-discovery.md — Rule 0: classify new directives
 - @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/rules/anti-laziness.md — Rule 6: 3-attempts escalation
-- REF-909 (Anthropic — *Effective Harnesses for Long-Running Agents*) — initializer-agent / coding-agent pattern, progress files. Induction: [roctinam/research-papers#615](https://git.integrolabs.net/roctinam/research-papers/issues/615). Source URL: https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
-- REF-910 (Anthropic — *Compaction*) — auto-compact mechanics, Compact Instructions, what survives. Induction: [roctinam/research-papers#616](https://git.integrolabs.net/roctinam/research-papers/issues/616). Source URL: https://platform.claude.com/docs/en/build-with-claude/compaction
+- REF-909 (Anthropic — *Effective Harnesses for Long-Running Agents*) — initializer-agent / coding-agent pattern, progress files. Source URL: https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
+- REF-910 (Anthropic — *Compaction*) — auto-compact mechanics, Compact Instructions, what survives. Source URL: https://platform.claude.com/docs/en/build-with-claude/compaction
 - REF-122 (Verma — *Active Context Compression / Focus Agent*) — aggressive vs passive compression discipline (22.7% vs 6%)
 - REF-128 (Zylos Research — *Context Window Management Strategies*) — effective context is 30-40% smaller than advertised
 - Commissioning anchor: [roctinam/aiwg#1348](https://git.integrolabs.net/roctinam/aiwg/issues/1348)

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

@@ -0,0 +1,68 @@
+---
+namespace: aiwg
+name: aiwg-mission
+platforms: [all]
+kernel: true
+description: Launch an AIWG Mission — durable, audited dynamic agent orchestration toward a completion criterion. AIWG owns the conductor (activity-log, gates, best-output, checkpoint/resume, cost); native primitives drive worker mechanism. Surfaces as /aiwg-mission in Codex (AIWG-owned, no plugin dependency).
+---
+
+# AIWG Mission
+
+You are launching (or participating in) an **AIWG Mission** — AIWG's dynamic, durable, audited agent orchestration. A Mission decomposes a goal into worker cycles, runs them toward a measurable completion criterion, and aggregates the result, while AIWG owns the bookkeeping and gates regardless of which agent stack each worker runs on.
+
+This is an **AIWG-specific kernel capability**. On Codex it surfaces as `/aiwg-mission`, deployed by AIWG to `~/.codex/prompts/` — it is **AIWG-owned**, not the plugin-provided `/workflow` an arbitrary Codex install may or may not have (`/workflow` is not a core Codex primitive — see `.aiwg/research/provider-workflow-integration.md`).
+
+## Mission vs Flow vs in-stack primitive
+
+- **Mission** (this skill) = *dynamic* orchestration. The shape emerges at run time from the goal. Cross-stack capable.
+- **Flow** = a *pre-established* declarative YAML sequence (`flow.aiwg.io/v1`); use `aiwg discover` to find a matching Flow before improvising a Mission.
+- **In-stack primitive** (Codex `/goal`, Claude's Workflow tool) = orchestrates *within one stack's process/turn*. A Mission may dispatch workers **to** these; they do not replace the Mission conductor.
+
+## When this fires
+
+Natural-language triggers:
+
+- "launch a mission" / "start an AIWG mission"
+- "orchestrate this across agents"
+- "fan this out to several agents and aggregate"
+- "spawn workers to do X until Y"
+- "run a long unattended orchestration"
+- "coordinate Codex and Claude agents on this" (cross-stack — see #1546)
+
+Non-triggers (route elsewhere):
+
+- A single focused task → just do it (no orchestration overhead; see `god-session` / `subagent-scoping`).
+- A pre-established repeatable sequence → find the **Flow** via `aiwg discover` (e.g. `flow-release`, `flow-deploy-to-production`).
+- An in-session "iterate until condition" on one stack → the provider-native `/goal` (Codex, Claude Code) already routes for that (#1451/#1469).
+- "Address open issues" → the `address-issues` skill (which may itself run as a Mission).
+
+## How to run a Mission
+
+1. **State the completion criterion measurably** (per the `vague-discretion` rule). "good enough" is not a criterion; "all tests pass and CI green", "score ≥ 85", "every flagged finding verified" are. If the user's goal is vague, extract a checkable criterion first.
+
+2. **Right-size + decompose.** Break the goal into independently-verifiable worker cycles (`subagent-scoping`). Decide single-stack vs cross-stack:
+   - **Single-stack** (default): workers run on the current stack. Use this stack's native primitive for in-session fan-out where available; otherwise AIWG's external loop.
+   - **Cross-stack** (#1546): when the operator wants heterogeneous stacks (e.g. Claude conductor → Codex workers), dispatch worker cycles to executors advertising the target `stack:<name>` capability via AIWG's `serve` executor-registry. The conductor stays AIWG-owned.
+
+3. **Dispatch.** For durable/detached/unattended Missions use AIWG's external route (`aiwg mc dispatch` / `ralph-external`) so the Mission survives the session ending. For in-session orchestration, the native primitive may drive the *mechanism* — but AIWG still owns everything in step 4.
+
+4. **Retain ownership (non-negotiable, identical across stacks).** Whatever drives the worker mechanism, AIWG owns:
+   - activity-log entries (per the `activity-log` rule)
+   - issue-thread comments / progress
+   - human-authorization + threat gates (per `human-authorization`)
+   - best-output selection across cycles
+   - crash-resilient checkpoint/resume (durability)
+   - reproducibility + cost tracking
+
+5. **Converge + report.** Run cycles until the completion criterion is met (with a `max-cycles` escape hatch), select the best output, and report what each worker did and the aggregated result. Apply the anti-laziness recovery protocol (PAUSE→DIAGNOSE→ADAPT→RETRY→ESCALATE) rather than abandoning on failure.
+
+## Discover before improvising
+
+Before hand-rolling a Mission, run `aiwg discover "<the goal>"` — a curated Flow or skill may already exist (the `skill-discovery` rule). A Mission is for genuinely *dynamic* orchestration where no pre-established Flow fits.
+
+## References
+
+- `.aiwg/architecture/adr-workflow-routing.md` — routing + cross-stack amendment
+- `.aiwg/research/provider-workflow-integration.md` — why Codex `/workflow` is not core (#1535)
+- #1534 (epic), #1544 (this command), #1546 (cross-stack Missions), #1536 (Missions/Flows naming)
+- `aiwg mc` (mission-control) — the durable dispatch surface

package/agentic/code/addons/aiwg-utils/workflow/README.md

@@ -0,0 +1,118 @@
+# AIWG Flows Metalanguage (core primitive)
+
+`apiVersion: flow.aiwg.io/v1` (forward) — `workflow.aiwg.io/v1` accepted for back-compat
+
+> **Naming (#1536):** this declarative spec defines **Flows** (pre-established,
+> authored sequences). The complementary **dynamic** orchestration concept is a
+> **Mission** (`mc` mission-control). "Workflow" was the original name and
+> collides with provider `/workflow` commands, so AIWG uses **Flows + Missions**.
+> Wire identifiers are dual-recognized — `flow.aiwg.io/v1` + `Flow*` kinds are
+> the forward spelling; `workflow.aiwg.io/v1` + `Workflow*` remain valid (mirrors
+> the existing `ops.aiwg.io/v1` alias). No authored document breaks; the
+> `workflow.*` spelling is deprecated for removal no earlier than the release
+> after this alias ships. See `.aiwg/architecture/adr-workflow-naming.md`.
+
+A declarative YAML spec for composing automation work. Any AIWG framework, addon, or extension can author workflows in this language and route them through the shared executor. The metalanguage is a **core utility primitive** — it ships in `aiwg-utils` so every install has access to it, regardless of which frameworks are deployed.
+
+## What this replaces
+
+This metalanguage was originally authored as `ops.aiwg.io/v1` under `ops-complete`. The shape — capability + playbook + inventory + target + gate — is generic; the `Ops` label was a packaging artifact. Lifting the spec to `aiwg-utils` makes it usable by any domain (release validation, content production, research orchestration, CI/CD) without forcing the consumer to depend on ops-complete.
+
+`ops.aiwg.io/v1` documents still parse via apiVersion alias (see `docs/migration-from-ops.md`); no existing playbook breaks.
+
+## The 7 kinds
+
+| Kind | Purpose | Schema |
+|---|---|---|
+| **WorkflowCapability** | A reusable named verb with declared inputs, outputs, verification command, and executor agent | [schemas/workflow-capability.schema.json](schemas/workflow-capability.schema.json) |
+| **WorkflowPlaybook** | A DAG of capability invocations against a target inventory, with retry / depends_on / gates | [schemas/workflow-playbook.schema.json](schemas/workflow-playbook.schema.json) |
+| **WorkflowInventory** | Declarative target set (hosts, providers, environments, anything addressable) | [schemas/workflow-inventory.schema.json](schemas/workflow-inventory.schema.json) |
+| **WorkflowTarget** | A single addressable resource referenced from inventory | [schemas/workflow-target.schema.json](schemas/workflow-target.schema.json) |
+| **WorkflowGate** | A pause point for human-in-the-loop authorization or judgment | [schemas/workflow-gate.schema.json](schemas/workflow-gate.schema.json) |
+| **WorkflowRole** | A bundle of capabilities scoped to a role identity for permission boundaries | [schemas/workflow-role.schema.json](schemas/workflow-role.schema.json) |
+| **WorkflowExtension** | A domain-specific extension declaring its own apiVersion namespace, kinds, and capability bundle | [schemas/workflow-extension.schema.json](schemas/workflow-extension.schema.json) |
+
+## Authoring model
+
+Three layers from most reusable to most specific:
+
+```
+[ core metalanguage ]   apiVersion: workflow.aiwg.io/v1     ← lives in aiwg-utils (this spec)
+        ↑
+[ domain extension ]    apiVersion: <domain>.workflow.aiwg.io/v1   ← e.g. ops, validation, research
+        ↑
+[ user instance  ]      a specific Capability or Playbook in a project    ← lives in .aiwg/workflow/
+```
+
+The core metalanguage defines the *shape* of capabilities, playbooks, inventories, etc. A domain extension declares its own `apiVersion` namespace and contributes its own capability library. A user instance is a single capability or playbook file in a project's `.aiwg/workflow/` directory.
+
+## Where files live
+
+| Layer | Location |
+|---|---|
+| Core schemas (this addon) | `agentic/code/addons/aiwg-utils/workflow/schemas/` |
+| Core docs | `agentic/code/addons/aiwg-utils/workflow/docs/` |
+| Domain extension (e.g. `ops`) | `agentic/code/frameworks/ops-complete/capabilities/` |
+| Domain extension (e.g. `validation`) | `agentic/code/frameworks/validation-complete/capabilities/` |
+| User instance (per project) | `.aiwg/workflow/capabilities/` and `.aiwg/workflow/playbooks/` |
+
+## Executor contract
+
+A single agent satisfies the executor contract for every workflow kind, regardless of domain. Today that agent is `ops-runbook-executor` (under ops-complete) — it will be renamed/lifted to `workflow-executor` as part of the lift (see migration plan).
+
+The contract:
+
+1. **Resolve**: load the playbook, resolve every `capability:` reference, validate each capability against its schema.
+2. **Plan**: build the step DAG from `depends_on` edges; reject cycles.
+3. **Bind**: bind playbook `vars` and per-step `inputs` into capability inputs; resolve `from: <step-id>.<output>` references after step completion.
+4. **Execute**: for each ready step, dispatch to the capability's `agent`. Capture stdout/stderr/exit-status. If `verification.command` is present, run it and compare against `verification.expect`.
+4a. **Fan-out** (`fanout` step, #1547): when a step carries a `fanout` block instead of a `capability`, dispatch each `fanout.agents[*]` capability — concurrently for `strategy: parallel` (a review panel), or chained (each agent sees the prior output) for `strategy: pipeline`. Await all panel agents, collect their structured outputs, then dispatch `fanout.synthesize` with the panel outputs as input; the synthesis result is the step's output for downstream `from:`/`depends_on` consumers. The retained-ownership invariant applies **across the whole panel**: audit every panel agent + the synthesis (step 7), honor gates/authorization, and apply best-output selection over the panel. This is the declarative spelling of the multi-agent documentation pattern (Primary → Parallel Reviewers → Synthesizer); see `.aiwg/architecture/adr-flow-agentic-steps.md`. A step MUST NOT set both `capability` and `fanout`.
+5. **Gate**: when a `kind: gate` step is reached, pause; surface the gate's `description` and `inputs` to the human; resume when the gate is acknowledged.
+6. **Retry**: respect each step's `retry.limit` and `retry.on` policy.
+7. **Audit**: append every step outcome (start, end, verification result, outputs, gate decisions) to `.aiwg/workflow/runs/<run-id>/audit.jsonl`.
+8. **Report**: at playbook completion, emit a structured report to `.aiwg/workflow/runs/<run-id>/report.md`.
+
+The executor MUST NOT mutate the playbook or its capabilities. It MUST honor `idempotent: true` (re-runs against the same target produce the same outcome). It MUST refuse to execute capabilities whose `target_requirements` are unmet (missing OS, missing binary, missing access).
+
+## Cross-stack Missions (#1546)
+
+A **Mission** (dynamic orchestration) can fan worker cycles across *heterogeneous agentic stacks* — e.g. a Claude-conductor Mission dispatching a worker (or a `fanout` panel agent) to a **Codex** executor, or a single Mission spanning multiple stacks under one durable conductor. This needs **no new transport**: the `serve` executor registry already routes by capability.
+
+- **Convention:** an executor advertises its stack via the established `runtime:<name>` capability — `runtime:codex`, `runtime:claude-code` (already in the `serve` fixtures). Do **not** invent a parallel `stack:<name>` token.
+- **Dispatch:** the conductor selects a worker's stack with an `executor_filter` on that capability; `src/serve/agent-router.ts` `routeMission()` / `ExecutorRegistry.pickByFilter()` pick a connected executor advertising **all** filtered capabilities. A `fanout` step's panel agents may each target a different `runtime:<name>` — the YAML `fanout` is the cross-stack authoring surface.
+- **Invariant (across stacks):** the conductor retains activity-log, human-authorization/threat gates, best-output selection, checkpoint/resume durability, reproducibility, and cost — regardless of which stack each worker ran on. The per-stack executor drives the *worker mechanism* only.
+
+See `.aiwg/architecture/adr-workflow-routing.md` (cross-stack amendment).
+
+## Apiversion aliasing
+
+For backward compatibility, the executor accepts the following apiVersion equivalences:
+
+| Legacy | Resolves to |
+|---|---|
+| `ops.aiwg.io/v1` | `workflow.aiwg.io/v1` |
+| `sys.ops.aiwg.io/v1` | `sys.workflow.aiwg.io/v1` |
+| `it.ops.aiwg.io/v1` | `it.workflow.aiwg.io/v1` |
+| `dev.ops.aiwg.io/v1` | `dev.workflow.aiwg.io/v1` |
+| `stream.ops.aiwg.io/v1` | `stream.workflow.aiwg.io/v1` |
+
+Equivalence is bidirectional for the v1 line. The aliasing layer is removed when `ops` and its extensions are migrated to native `workflow.*` apiVersions (target: release after the lift ships).
+
+## Why this lives in aiwg-utils
+
+- **Universal**: every AIWG install carries `aiwg-utils`; the workflow metalanguage is available without installing a domain framework first.
+- **No domain bias**: the schemas describe shape only — they say nothing about hosts, services, certs, or providers. Domain semantics live in domain extensions.
+- **One executor, many domains**: ops, validation, and any future domain share the same DAG runner, the same audit format, the same gate semantics.
+
+## What's NOT in scope
+
+- The executor implementation. The agent that runs playbooks lives outside the spec (currently `ops-runbook-executor`, lifted later).
+- Domain-specific capability libraries. Each domain authors its own. This addon ships zero capabilities — only the spec.
+- Per-language SDKs / bindings. The spec is the authoritative contract; bindings can be written but aren't required.
+
+## See also
+
+- `docs/overview.md` — narrative tour of the metalanguage with worked examples
+- `docs/migration-from-ops.md` — how existing `ops.aiwg.io/v1` documents migrate
+- `examples/` — minimal authored examples for each kind
+- ops-complete (`agentic/code/frameworks/ops-complete/`) — the first domain consumer; will be migrated to native `workflow.*` apiVersion in a follow-up

package/agentic/code/addons/aiwg-utils/workflow/docs/migration-from-ops.md

@@ -0,0 +1,142 @@
+# Migration: `ops.aiwg.io/v1` → `workflow.aiwg.io/v1`
+
+The workflow metalanguage (this addon) is the lifted form of what shipped originally as `ops.aiwg.io/v1` under `ops-complete`. Existing playbooks and capabilities continue to work via apiVersion aliasing. This doc describes the migration path for consumers who want to author against the new namespace directly.
+
+## What changed
+
+| Aspect | Before | After |
+|---|---|---|
+| Where the spec lives | `agentic/code/frameworks/ops-complete/schemas/metalanguage/` | `agentic/code/addons/aiwg-utils/workflow/schemas/` |
+| Schema names | `ops-capability.schema.json`, etc. | `workflow-capability.schema.json`, etc. |
+| `apiVersion` | `ops.aiwg.io/v1` (and `<ext>.ops.aiwg.io/v1` for extensions) | `workflow.aiwg.io/v1` (and `<ext>.workflow.aiwg.io/v1`) |
+| `kind` | `OpsCapability`, `OpsPlaybook`, … | `WorkflowCapability`, `WorkflowPlaybook`, … |
+| Schema `$id` URL | `https://aiwg.io/schemas/ops/v1/ops-X.schema.json` | `https://aiwg.io/schemas/workflow/v1/workflow-X.schema.json` |
+| Executor agent | `ops-runbook-executor` | `workflow-executor` (alias of the same agent during the migration window) |
+| Carrying addon | `ops-complete` (heavyweight) | `aiwg-utils` (universal core) |
+
+What did NOT change:
+
+- Field names within each kind's `spec` block (same `inputs`, `outputs`, `verification`, `target_requirements`, `depends_on`, `gate.description`, …).
+- Capability semantics. A `verify-tls-expiry` capability authored against the ops apiVersion behaves identically when migrated.
+- Inventory/target structure.
+- Audit trail format.
+
+The lift is a rename pass and a relocation. No field-level semantics change.
+
+## Apiversion aliasing (transitional)
+
+While both apiVersions exist, the executor accepts these equivalences for the v1 line:
+
+| Legacy apiVersion | Resolves to |
+|---|---|
+| `ops.aiwg.io/v1` | `workflow.aiwg.io/v1` |
+| `sys.ops.aiwg.io/v1` | `sys.workflow.aiwg.io/v1` |
+| `it.ops.aiwg.io/v1` | `it.workflow.aiwg.io/v1` |
+| `dev.ops.aiwg.io/v1` | `dev.workflow.aiwg.io/v1` |
+| `stream.ops.aiwg.io/v1` | `stream.workflow.aiwg.io/v1` |
+
+A document carrying the legacy apiVersion validates against the legacy schema and is normalized to the workflow apiVersion before execution. Outputs and audit-trail entries carry the workflow apiVersion regardless of input.
+
+The legacy schemas continue to live under `ops-complete` for the v1 line's lifetime. When the v2 line ships, only `workflow.aiwg.io/v2` exists and `ops.aiwg.io/v1` documents will need explicit migration to v2.
+
+## Migrating an existing capability
+
+Mechanical rewrite:
+
+```diff
+- apiVersion: ops.aiwg.io/v1
+- kind: OpsCapability
++ apiVersion: workflow.aiwg.io/v1
++ kind: WorkflowCapability
+  metadata:
+    name: check-tls-expiry
+    labels:
+      category: pki
+  spec:
+    description: Check a TLS certificate's expiry date
+    version: "1.0.0"
+    inputs:
+      - name: hostname
+        type: string
+        required: true
+    # ... rest unchanged
+    agent: cert-lifecycle-monitor
+    idempotent: true
+    verification:
+      command: "openssl s_client -connect {{ hostname }}:443 </dev/null | openssl x509 -noout -dates"
+      expect: "notAfter="
+```
+
+Two lines change. The rest of the document is untouched.
+
+If the capability lives inside a domain extension (`<ext>.ops.aiwg.io/v1`), the migration is:
+
+```diff
+- apiVersion: sys.ops.aiwg.io/v1
+- kind: OpsCapability
++ apiVersion: sys.workflow.aiwg.io/v1
++ kind: WorkflowCapability
+```
+
+## Migrating an existing playbook
+
+Same shape — change the apiVersion line and the kind line. Step references to capabilities continue to resolve by name; the executor looks across all registered extension namespaces.
+
+```diff
+- apiVersion: ops.aiwg.io/v1
+- kind: OpsPlaybook
++ apiVersion: workflow.aiwg.io/v1
++ kind: WorkflowPlaybook
+  metadata:
+    name: rotate-tls-cert
+  spec:
+    inventory: production-web-tier
+    targets:
+      groups: [edge]
+    steps:
+      - id: pre-check
+        capability: check-tls-expiry           # still resolves by capability name
+        # ... rest unchanged
+```
+
+## Migrating an inventory / target / gate / role / extension
+
+Pattern repeats — change apiVersion and kind, nothing else.
+
+| Legacy kind | New kind |
+|---|---|
+| `OpsCapability` | `WorkflowCapability` |
+| `OpsPlaybook` | `WorkflowPlaybook` |
+| `OpsInventory` | `WorkflowInventory` |
+| `OpsTarget` | `WorkflowTarget` |
+| `OpsGate` | `WorkflowGate` |
+| `OpsRole` | `WorkflowRole` |
+| `OpsExtension` | `WorkflowExtension` |
+
+## When to migrate
+
+- **New work**: author against `workflow.aiwg.io/v1` directly. No reason to use the legacy apiVersion for new capabilities or playbooks.
+- **Existing ops-complete capabilities**: stay on `ops.aiwg.io/v1` until the next routine touch (capability update, schema change, new extension version). Aliasing means there's no urgency.
+- **`ops-complete` itself**: a single coordinated migration PR renames the apiVersion across all capabilities/playbooks and updates `manifest.json`. Plan to do this once ahead of the v2 schema work, not piecemeal.
+
+## Validation
+
+To validate a migrated document against the new schemas:
+
+```bash
+# Using ajv or any JSON Schema validator
+ajv validate \
+  -s agentic/code/addons/aiwg-utils/workflow/schemas/workflow-capability.schema.json \
+  -d path/to/your-capability.yaml
+```
+
+`aiwg validate-metadata` includes the workflow schemas in its corpus and will flag capability/playbook documents that fail validation.
+
+## Tracking
+
+- Spec lift (this work): authored under `agentic/code/addons/aiwg-utils/workflow/`. Schemas, README, overview, this doc.
+- Executor alias (`workflow-executor` → `ops-runbook-executor`): follow-up.
+- `ops-complete` migration to native `workflow.*` apiVersion: follow-up after the executor alias lands.
+- `sdlc-complete/flows/` consolidation onto the workflow metalanguage: follow-up; not part of the initial lift.
+
+Track via the planning issue (see release-validation epic comments).