@lumenflow/cli 5.3.2 → 5.5.0

package/templates/core/LUMENFLOW.md.template

@@ -205,7 +205,7 @@ intentionally exempt and the workspace policy does not already exclude it.
 ## Core Principles
 
 1. **Design-First** (feature/refactor WUs): Load the `design-first` skill before implementation. Question requirements, delete unnecessary, simplify before optimizing. Invocation varies by vendor — see [Skills & Agents](#skills--agents) below.
-2. **Fit-For-Surface Verification**: Choose the least brittle verification that gives strong confidence. Prefer TDD for runtime logic when repository policy requires it; prefer behavior-focused integration, smoke, visual, or manual verification for UI, content, and presentation work. Never assert inline styles, CSS values, exact copy, or DOM shape in E2E/integration tests.
+2. **Fit-For-Surface Verification**: Choose the least brittle verification that gives strong confidence. Prefer TDD for runtime logic when repository policy requires it; prefer behavior-focused integration, smoke, visual, or manual verification for UI, content, and presentation work. Never assert inline styles, CSS values, exact copy, or DOM shape in E2E/integration tests. For the boundary between framework-owned gates, generated brief content, and consumer-authored local guidance, see [ADR-017](docs/09-architecture-decisions/ADR-017-lumenflow-configurability-principle.md).
 3. **Library-First**: Search existing libraries before custom code
 4. **DRY/SOLID/KISS/YAGNI**: No magic numbers, no hardcoded strings
 5. **Worktree Discipline**: After `wu:claim`, work ONLY in the worktree
@@ -252,17 +252,59 @@ pnpm mem:inbox                    # coordination signals (defaults to unread)
 The memory layer also supports live-session addressing for active agents:
 
 ```bash
-pnpm mem:roster                             # list active session_id/display_name/role rows
-pnpm mem:signal 'please review' --wu WU-XXXX --to Planck
-pnpm mem:inbox --for Planck                 # targeted + broadcast signals for that session
+pnpm mem:roster                             # list active session_id/display_name/agent_identity/role rows
+pnpm mem:signal 'please review' --wu WU-XXXX --to Planck,codex:implementer:host42 --intent PROPOSE --requires-ack
+pnpm mem:inbox --for Planck --thread thread-1234  # directed + broadcast signals for that identity
+pnpm mem:converged --thread thread-1234      # exit 0 when every root recipient replied AGREE
 pnpm mem:context --wu WU-XXXX --no-roster   # opt out when a test needs stable output
 ```
 
+The wire contract for agent-to-agent coordination is `A2A.V1`, exported from
+`@lumenflow/control-plane-sdk/a2a`. Local files under `.lumenflow/memory/`, the
+Claude `PostToolUse` hook, and `mem:watch` are adapters over that contract, not
+separate schemas. `workspace_id` is optional for local worktrees and required
+for hosted transports such as lumenflow.cloud, where it is the tenant/workspace
+routing key.
+
 `display_name` is an ephemeral live-session handle, not a stable role alias. It
 is assigned from `.lumenflow/agents/display-name-pool.yaml` when a session
 starts and released when the session ends. `mem:signal --to` / `mem:inbox --for`
-resolve either a `session_id` or a current `display_name` against the live
-roster before reading or writing `target_agent`.
+accept a `session_id`, current `display_name`, or explicit `agent_identity`.
+`mem:signal --to` also accepts comma-separated recipients. Directed signals are
+persisted as canonical A2A `recipients[]`; `target_agent` remains only as the
+single-recipient legacy alias.
+
+`agent_identity` is an explicit stable reader identity for A2A receipt
+coalescing across restarts or concurrent sessions. Set it with
+`pnpm agent:session --agent-identity <owner>:<role>:<purpose>` or
+`LUMENFLOW_AGENT_IDENTITY`; LumenFlow never derives it from PID, hostname, or
+runtime metadata. When it is absent, receipt state falls back to the ephemeral
+`session_id`.
+
+A2A signal semantics are structured, not prose-only. `mem:signal` supports
+`--thread`, `--reply-to`, `--intent INFO|PROPOSE|COUNTER|AGREE|REJECT`,
+`--interrupt advisory|priority|urgent|soon|immediate`, and `--requires-ack`.
+Directed root signals default to `interrupt_class: priority` and get a generated
+`thread_id`; broadcasts default to `interrupt_class: advisory`. Replies inherit
+the parent thread unless `--thread` is explicit. When a recipient posts
+`--intent AGREE` or `--intent REJECT` on that thread, the root signal receipt is
+promoted to `acked` or `rejected`, and `mem:converged --thread <id>` reports
+whether every root recipient has agreed. Local JSONL remains only the dev
+adapter over `A2ASignalV1` / `A2AReceiptV1`; lumenflow.cloud should use the same
+contract over its hosted transport.
+
+Claude Code projects with generated LumenFlow hooks receive addressed
+`signal:received` events at the next `PostToolUse` boundary. The hook surfaces
+`intent`, `interrupt_class`, `requires_ack`, and same-thread ACK/REJECT commands
+without replacing the `wu:prep` unread-directed-signal gate. Other local clients
+can run `pnpm mem:watch --session <session_id|display_name|agent_identity>` in
+a side terminal for foreground `signal:received` delivery through the same event
+queue and receipt model.
+
+Before `wu:prep`, any unread directed signal addressed to the current reader on
+the WU or its initiative is a decision point. Read, ACK, or dismiss it before
+continuing. `pnpm wu:prep --allow-unread-signals --reason '<audit reason>'`
+exists for explicit audited overrides only.
 
 ### During the WU (capture, don't hoard)
 
@@ -552,6 +594,126 @@ For the full worktree lifecycle (parallel execution, bootstrap, isolation guaran
 | `pnpm typecheck`                  | Run TypeScript type checking                               |
 | `pnpm test`                       | Run all tests (Vitest)                                     |
 
+#### Per-gate skip (WU-2925)
+
+`pnpm wu:prep` and `pnpm wu:done` accept `--skip-gate <name>` (repeatable) to
+suppress a single named gate. The legacy `--skip-gates` (binary) is deprecated
+for one minor cycle and emits a deprecation warning pointing to the public
+[Gates Reference](https://lumenflow.dev/reference/gates#per-gate-skip); use
+`--skip-gate` per gate.
+
+```bash
+# Skip a single environmental gate (allow-list)
+pnpm wu:done --id WU-XXX --skip-gate lane-health \
+  --reason "pre-existing 50-file coverage gap" --fix-wu WU-YYY
+
+# Repeat the flag to skip multiple gates
+pnpm wu:prep --id WU-XXX \
+  --skip-gate lane-health --skip-gate migration-verify \
+  --reason "no DB infra in agent worktree" --fix-wu WU-YYY
+```
+
+**Allow-list (skippable: true by default):** `migration-verify`,
+`lane-health`, `tdd-diff-evidence`, plus the WU-2927 opt-in local-prep gates
+`build`, `integration-test`, `e2e-smoke`. All other framework gates default to
+`skippable: false` and require a per-repo override at
+`software_delivery.gates.overrides.<gate_id>.skippable=true` to be skipped:
+
+```bash
+pnpm config:set software_delivery.gates.overrides.db-dod-gate.skippable=true
+```
+
+Audit format gains a discriminated `source` field
+(`agent` | `auto-skip-not-applicable` | `auto-skip-missing-prereq` | `blocked`)
+and a `lifecycle` field (`prep` | `done`) so the trail spans both lifecycle
+commands. Legacy entries without `source` are read as `agent` for DORA/CFR
+back-compat. CFR (Change Failure Rate) only counts `source: 'agent'` rows;
+auto-skips and blocks are excluded.
+
+MCP exposes both `skip_gate` (array, preferred) and `skip_gates` (boolean,
+deprecated) for one minor cycle, symmetric with the CLI.
+
+#### Discriminated GateResult states (WU-2926)
+
+Each gate run produces one of six `GateResult` discriminated states. Stable
+glyphs/labels (also surfaced verbatim in the public
+[Gates Reference](https://lumenflow.dev/reference/gates#discriminated-gateresult-states)):
+
+| State                         | Glyph               | Meaning                                                                                               |
+| ----------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------- |
+| `passed`                      | ✅ PASSED           | Gate ran successfully.                                                                                |
+| `failed`                      | ❌ FAILED           | Gate ran and failed (or `applicable + missing + skippable + 'fail'`).                                 |
+| `skipped-by-agent`            | ⏭ SKIPPED-BY-AGENT | Explicit `--skip-gate <name>` (audit `source: 'agent'`).                                              |
+| `skipped-auto-not-applicable` | ⊘ AUTO-SKIPPED      | `checkApplicability` returned not-applicable (audit `source: 'auto-skip-not-applicable'`).            |
+| `skipped-auto-missing-prereq` | ⊘ AUTO-SKIPPED      | Applicable + missing prereq + skippable + `'auto-skip'` (audit `source: 'auto-skip-missing-prereq'`). |
+| `blocked-missing-prereq`      | 🚫 BLOCKED          | Applicable + missing prereq + `skippable: false` (audit `source: 'blocked'`, exits non-zero).         |
+
+Decision matrix:
+
+| Applicability  | Preconditions | Skippable | `prereq_strategy` | Result                           |
+| -------------- | ------------- | --------- | ----------------- | -------------------------------- |
+| not-applicable | —             | —         | —                 | `skipped-auto-not-applicable`    |
+| applicable     | satisfied     | —         | —                 | run → `passed` or `failed`       |
+| applicable     | missing       | false     | —                 | `blocked-missing-prereq` (BLOCK) |
+| applicable     | missing       | true      | `'auto-skip'`     | `skipped-auto-missing-prereq`    |
+| applicable     | missing       | true      | `'fail'`          | `failed`                         |
+
+Each `GateDefinition` may implement `checkApplicability` and
+`checkPreconditions`. Defaults return `'applicable'` and `'satisfied'` so
+existing simple gates inherit always-runs semantics with no per-gate code
+change. `safety-critical-test` ships with `skippable_default: false` and a
+default applicability of `'applicable'` for every change set — preserving
+today's runs-on-every-WU behaviour. Per-repo override:
+
+```bash
+# Narrow safety-critical-test applicability without flipping the default
+pnpm config:set software_delivery.gates.overrides.safety-critical-test.applicability_paths \
+  --json-value '["app/security/**","lib/auth/**"]'
+```
+
+Auto-skip + blocked states write audit NDJSON with the discriminated `source`
+field; CFR only counts `source: 'agent'` rows so auto-skips and blocks never
+inflate change-failure-rate.
+
+#### Extended local-prep profile (WU-2927)
+
+`software_delivery.gates.local_prep` is an opt-in profile that extends
+`wu:prep` with the build / integration-test / e2e-smoke gates that previously
+only ran in CI. Driven by lumenflow.cloud's three P0 hotfixes in 24h
+(WU-1497..WU-1499) — each slipped past local gates because `wu:prep` did not
+run `pnpm build`, `pnpm test:integration`, or `pnpm test:e2e --smoke`.
+
+```yaml
+software_delivery:
+  gates:
+    local_prep:
+      build:
+        enabled: false # opt-in: pnpm build on every wu:prep
+      integration_test:
+        enabled: false # opt-in: pnpm test:integration on every wu:prep
+      e2e_smoke:
+        enabled: false # opt-in: pnpm test:e2e --tag <tag>
+        tag: smoke
+      latency_budget_warn_ms: 180000 # 3 min soft warn, never blocks
+```
+
+| Field                       | Default           | Effect                                                                                                                                                                                                                                       |
+| --------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `build.enabled`             | `false`           | When `true`, registers a build gate that runs `pnpm build`. `prereq_strategy: 'fail'` — missing `build` script in `package.json` is a misconfig (`failed`), not an environmental gap.                                                        |
+| `integration_test.enabled`  | `false`           | When `true`, makes the (now unconditionally registered) `integration-test` gate applicable. Runs `RUN_INTEGRATION_TESTS=1 pnpm vitest run '**/*.integration.*' '**/golden-*.test.*'`. Missing script → `failed`.                             |
+| `e2e_smoke.enabled` + `tag` | `false` / `smoke` | When `true` AND `playwright.config.{ts,js,mjs}` exists at repo root, registers an `e2e-smoke` gate that runs `pnpm test:e2e --tag <tag>`. Repos without Playwright are auto `not-applicable` (clean opt-out — no explicit disable required). |
+| `latency_budget_warn_ms`    | `180000`          | `wu:prep` prints total elapsed seconds; if it exceeds the budget, emits a non-failing warning. Soft signal only.                                                                                                                             |
+
+All three gates are added to the `--skip-gate` allow-list (`skippable: true`),
+extending WU-2925's initial `{migration-verify, lane-health, tdd-diff-evidence}`
+set. Rationale: local-prep gates are opt-in environmental gates; agents need
+`--skip-gate <name>` for legitimate hotfix scenarios where the gate is broken
+or irrelevant for that WU. Skips are captured in audit per WU-2925 semantics
+with `source: 'agent'`.
+
+Backward-compat: omitting `local_prep` (the default) preserves today's
+behaviour — none of the new gates is applicable, no new commands run.
+
 ### Lane Management
 
 | Command              | Description                                       |
@@ -578,7 +740,9 @@ For the full worktree lifecycle (parallel execution, bootstrap, isolation guaran
 | `pnpm mem:cleanup`    | Clean up stale memory data                 |
 | `pnpm mem:context`    | Get context for current lane/WU            |
 | `pnpm mem:create`     | Create memory node (bug discovery)         |
+| `pnpm mem:converged`  | Check A2A thread agreement                 |
 | `pnpm mem:inbox`      | Check coordination signals                 |
+| `pnpm mem:watch`      | Deliver A2A signal events without hooks    |
 | `pnpm mem:roster`     | List active sessions and display names     |
 | `pnpm mem:summarize`  | Summarize memory context                   |
 | `pnpm mem:triage`     | Triage discovered bugs                     |
@@ -635,6 +799,7 @@ For the full worktree lifecycle (parallel execution, bootstrap, isolation guaran
 | `pnpm lumenflow:doctor`         | Diagnose LumenFlow configuration                      |
 | `pnpm lumenflow:commands`       | List all available CLI commands                       |
 | `pnpm lumenflow:release`        | Run release workflow                                  |
+| `pnpm distribution:preflight`   | Audit consumer repos for npm-access flip readiness    |
 | `pnpm lumenflow:docs-sync`      | Refresh core docs, onboarding docs, and vendor assets |
 | `pnpm lumenflow:sync-templates` | Sync templates to project                             |
 | `pnpm lumenflow:upgrade`        | Upgrade LumenFlow packages                            |
@@ -678,19 +843,6 @@ For the full worktree lifecycle (parallel execution, bootstrap, isolation guaran
 | `pnpm pack:install`  | Install a domain pack into workspace       |
 | `pnpm pack:search`   | Search for domain packs in a registry      |
 
-### Audited Wrappers
-
-| Command            | Description                      |
-| ------------------ | -------------------------------- |
-| `pnpm file:read`   | Read file with audit trail       |
-| `pnpm file:write`  | Write file with audit trail      |
-| `pnpm file:edit`   | Edit file with audit trail       |
-| `pnpm file:delete` | Delete file with audit trail     |
-| `pnpm git:status`  | Show git status with audit trail |
-| `pnpm git:diff`    | Show git diff with audit trail   |
-| `pnpm git:log`     | Show git log with audit trail    |
-| `pnpm git:branch`  | Show git branch with audit trail |
-
 Commands include **context-aware validation** that checks location, WU status, and git state. When validation fails, commands provide copy-paste ready fix commands.
 
 ---
@@ -727,6 +879,16 @@ If you're an AI agent, read the onboarding docs:
 
 Skills are reusable workflow/knowledge bundles that agents load on demand. The `SKILL.md` format pioneered by Claude Code has converged into a de-facto standard adopted by OpenAI Codex (Dec 2025), Cursor (v2.4), and Windsurf Cascade (Jan 2026). LumenFlow stores vendor-neutral skill sources in `.lumenflow/skills/` and projects them to each vendor surface via `pnpm lumenflow:integrate --client <x>`.
 
+Agent plugins are a distribution on-ramp, not a replacement for these repo-level
+projections or for the Software Delivery Pack runtime. Per
+[ADR-018](docs/09-architecture-decisions/ADR-018-agent-plugin-distribution-boundary.md),
+standalone projected skills keep local names such as `design-first`, while
+plugin-installed Claude skills use plugin-qualified names such as
+`/lumenflow:design-first`. If both surfaces exist, prompts and handoff text must
+say which one they mean. Installing a plugin gives the agent methodology and
+entrypoint guidance; repo-level enforcement still requires `npx lumenflow init`,
+`pnpm lumenflow:integrate`, or `pnpm lumenflow:integrate --sync`.
+
 ### Core skills (vendor-neutral)
 
 | Skill                 | Load before...                               |
@@ -752,6 +914,15 @@ A skill name written in prose does nothing — it must be **loaded** through the
 | Aider        | `CONVENTIONS.md`          | `/read CONVENTIONS.md` or `aider --read CONVENTIONS.md`  |
 | Cline        | `.clinerules`             | Auto-loaded                                              |
 
+For plugin-distributed skills, prefer the vendor's plugin-qualified invocation
+surface instead of rewriting all canonical skill names. Claude Code plugin
+skills are namespaced as `/lumenflow:<skill>`. Codex plugin use should name the
+installed `lumenflow` plugin or one of its bundled skills through Codex's `@`
+plugin selection surface. **Plugin packaging is scoped under INIT-065 and not
+yet shipped as of 5.4.0** — these invocations apply once the packaging WUs land.
+Standalone projections remain valid until a future explicit cleanup command such
+as `--plugin-only` exists and is run intentionally.
+
 For vendor-specific setup details and per-vendor quirks, see:
 
 - Claude Code: [.claude/CLAUDE.md](.claude/CLAUDE.md)
@@ -794,6 +965,12 @@ Durable artifacts carry `requested_role` (from the orchestrator) and `actual_rol
 
 ---
 
+## Remote / MCP Dispatch
+
+LumenFlow ships `pnpm file:*` and `pnpm git:*` CLIs (`file:read`, `file:write`, `file:edit`, `file:delete`, `git:status`, `git:diff`, `git:log`, `git:branch`). These commands exist for non-native-tool agents (MCP remote dispatch, server-side sandbox). Local agents with native Read/Edit/Write should use those directly — they're faster and already audited via the client transcript. The wrappers are not part of the canonical local-development CLI surface.
+
+---
+
 ## References
 
 - [LumenFlow Agent Capsule]({{DOCS_OPERATIONS_PATH}}/_frameworks/lumenflow/lumenflow-agent-capsule.md) -- Full framework reference (lifecycle, lanes, gates, DoD)
@@ -802,5 +979,6 @@ Durable artifacts carry `requested_role` (from the orchestrator) and `actual_rol
 - [.lumenflow/constraints.md](.lumenflow/constraints.md) -- Non-negotiable rules and forbidden commands
 - [WU Sizing Guide]({{DOCS_OPERATIONS_PATH}}/_frameworks/lumenflow/wu-sizing-guide.md) -- Scoping work without needless fragmentation
 - [ADR-014: Typed Agent-Role Contract](docs/09-architecture-decisions/ADR-014-typed-agent-role-contract.md) — Canonical orchestration role vocabulary
+- [ADR-017: LumenFlow Configurability Principle](docs/09-architecture-decisions/ADR-017-lumenflow-configurability-principle.md) — Defaults are allowed; framework prescription must be configurable or consumer-authored
 - [Skills Index](.lumenflow/skills/INDEX.md)
 - [Agents README](.claude/agents/README.md)

package/templates/core/ai/onboarding/agent-invocation-guide.md.template

@@ -146,10 +146,6 @@ These surfaces already assemble the objective, scope, code paths, tests, recover
 constraints block, and evidence metadata. Do not prepend or append a second wrapper block around
 them.
 
-The role aliases referenced by these handoffs are vendor-neutral framework names (`general-purpose`,
-`lumenflow-pm`, `initiative-architect`, and so on). Client-specific overlays may implement those
-aliases differently, but the orchestration brief should keep the shared alias vocabulary intact.
-
 If you are building a fully custom or experimental prompt outside those canonical surfaces, use
 this structure:
 
@@ -218,7 +214,6 @@ Before spawning:
 
 - Confirm WU status and lane availability
 - Ensure worktree exists (or claim first)
-- Use the shared framework alias vocabulary in the brief, not vendor-specific display names
 - Provide explicit code_paths and tests
 - Require `mem:checkpoint` at 50+ tool calls
 - Require `mem:signal` for milestones

package/templates/core/ai/onboarding/agent-safety-card.md.template

@@ -98,7 +98,69 @@ not guess-and-retry.
 1. Read the error message
 2. Fix the underlying issue
 3. Re-run gates
-4. Never use `--skip-gates` for new failures
+4. Never use `--skip-gate` (or legacy `--skip-gates`) for new failures
+5. WU-2925: prefer `--skip-gate <name>` (repeatable, per-gate) over
+   `--skip-gates` (legacy binary, deprecated for one minor cycle). Only gates
+   marked `skippable: true` (allow-list: `migration-verify`, `lane-health`,
+   `tdd-diff-evidence`, plus the WU-2927 opt-in local-prep gates `build`,
+   `integration-test`, `e2e-smoke`) or overridden per-repo at
+   `software_delivery.gates.overrides.<gate_id>.skippable=true` may be skipped.
+   Both flags require `--reason` and `--fix-wu`.
+
+### Skip-vs-Block decision matrix (WU-2926)
+
+The runtime distinguishes six discriminated `GateResult` states with stable
+glyphs. The decision matrix encodes when a gate runs, auto-skips, or BLOCKS:
+
+| Applicability  | Preconditions | Skippable | `prereq_strategy` | Result                           | Glyph |
+| -------------- | ------------- | --------- | ----------------- | -------------------------------- | ----- |
+| not-applicable | —             | —         | —                 | `skipped-auto-not-applicable`    | ⊘     |
+| applicable     | satisfied     | —         | —                 | run → `passed` or `failed`       | ✅/❌ |
+| applicable     | missing       | false     | —                 | `blocked-missing-prereq` (BLOCK) | 🚫    |
+| applicable     | missing       | true      | `'auto-skip'`     | `skipped-auto-missing-prereq`    | ⊘     |
+| applicable     | missing       | true      | `'fail'`          | `failed`                         | ❌    |
+
+Key invariant: `applicable + missing + skippable=false` ALWAYS blocks. This is
+the silent-bypass guard. `--skip-gate <name>` cannot bypass it. The only
+escape hatch is a deliberate per-repo override at
+`software_delivery.gates.overrides.<gate_id>.skippable=true`, used only when
+the missing prerequisite is genuinely environmental (not a missing
+implementation).
+
+Audit NDJSON `source` field discriminates all four non-running outcomes:
+`agent` | `auto-skip-not-applicable` | `auto-skip-missing-prereq` | `blocked`.
+CFR/DORA only counts `source: 'agent'` so auto-skips and blocks never inflate
+change-failure-rate.
+
+### Override syntax (copy-pasteable, WU-2925/2926)
+
+```bash
+# Per-gate skip at wu:prep or wu:done (--skip-gate is repeatable)
+pnpm wu:prep --id WU-XXX --skip-gate lane-health \
+  --reason "no DB infra in agent worktree" --fix-wu WU-YYY
+
+# Make a non-allow-listed gate skippable per repo
+pnpm config:set software_delivery.gates.overrides.<gate_id>.skippable=true
+
+# Narrow a safety-critical gate's reach via applicability_paths
+# (preferred over flipping skippable for safety-critical gates)
+pnpm config:set software_delivery.gates.overrides.safety-critical-test.applicability_paths \
+  --json-value '["app/security/**","lib/auth/**"]'
+```
+
+### Latency-budget guidance (`local_prep` profile, WU-2927)
+
+The opt-in `software_delivery.gates.local_prep` profile extends `wu:prep` with
+`build`, `integration-test`, and `e2e-smoke` gates. All three are
+`skippable: true` and accept `--skip-gate <name>`. Latency budget defaults:
+
+- **`latency_budget_warn_ms: 180000`** (3 min): default soft warn, never blocks.
+- **60–90s**: tight, suits greenfield repos; expect false-positive warnings as
+  suites grow.
+- **5–10 min**: loose, suits monorepos with full Playwright; consider
+  `--skip-gate e2e-smoke` per-WU for cosmetic-only changes.
+
+Public reference: <https://lumenflow.dev/reference/gates#local_prep-profile-550>.
 
 ---
 

package/templates/core/ai/onboarding/initiative-orchestration.md.template

@@ -87,6 +87,10 @@ pnpm wu:brief --id WU-100 --client claude-code
 pnpm wu:delegate --id WU-100 --parent-wu WU-050 --client claude-code
 ```
 
+When the work is initiative decomposition or execution design rather than direct implementation, the
+default framework role to brief or delegate is `initiative-architect`. That role now replaces the
+retired docs-planning vocabulary in the default agent roster.
+
 **Use `wu:delegate` (not `wu:brief`) when:**
 
 - You are the orchestrator agent managing the initiative

package/templates/core/ai/onboarding/release-process.md.template

@@ -39,14 +39,14 @@ pnpm release --release-version 1.3.0 --skip-publish
 
 ### Options
 
-| Flag                        | Description                             |
-| --------------------------- | --------------------------------------- |
-| `--release-version <X.Y.Z>` | **Required.** Semver version to release |
-| `--dry-run`                 | Preview changes without making them     |
+| Flag                        | Description                                  |
+| --------------------------- | -------------------------------------------- |
+| `--release-version <X.Y.Z>` | **Required.** Semver version to release      |
+| `--dry-run`                 | Preview changes without making them          |
 | `--skip-publish`            | Skip npm publish only; validation still runs |
-| `--skip-build`              | Skip build step (use existing dist)     |
-| `--version`, `-V`           | Show CLI version                        |
-| `--help`, `-h`              | Show help                               |
+| `--skip-build`              | Skip build step (use existing dist)          |
+| `--version`, `-V`           | Show CLI version                             |
+| `--help`, `-h`              | Show help                                    |
 
 ### Examples
 

package/templates/core/ai/onboarding/vendor-support.md.template

@@ -31,15 +31,73 @@ lumenflow init
 
 For popular AI coding assistants, LumenFlow provides **optional enhanced integrations** with deeper features like auto-detection, skills, and vendor-specific configurations.
 
-| Assistant   | Config File                    | Auto-detected | Enhanced Features               |
-| ----------- | ------------------------------ | ------------- | ------------------------------- |
-| Claude Code | `CLAUDE.md`, `.claude/`        | Yes           | Skills, agents, hooks, settings |
-| Cursor      | `.cursor/rules/lumenflow.md`   | Yes           | Rules integration               |
-| Windsurf    | `.windsurf/rules/lumenflow.md` | Yes           | Rules integration               |
-| Cline       | `.clinerules`                  | No            | Rules file                      |
-| Codex       | `AGENTS.md` (native)           | No            | Uses universal files directly   |
-| Aider       | `.aider.conf.yml`              | No            | Config file                     |
-| Antigravity | `AGENTS.md` (native)           | Unknown       | Research phase                  |
+| Assistant   | Config File                                        | Auto-detected | Enhanced Features                                                |
+| ----------- | -------------------------------------------------- | ------------- | ---------------------------------------------------------------- |
+| Claude Code | `CLAUDE.md`, `.claude/`                            | Yes           | Skills, agents, hooks, settings, A2A `signal:received` delivery  |
+| Cursor      | `AGENTS.md`, `.cursor/rules/`                      | Yes           | Rules integration; foreground `mem:watch` A2A delivery           |
+| Windsurf    | `AGENTS.md`, `.agents/skills/`, `.windsurf/rules/` | Yes           | Rules integration plus shared skills; foreground `mem:watch` A2A |
+| Cline       | `.clinerules`                                      | No            | Rules file; foreground `mem:watch` or `mem:inbox` for A2A        |
+| Codex       | `AGENTS.md`, `.agents/skills/`, `.codex/agents/`   | No            | Universal files plus overlays; foreground `mem:watch` A2A        |
+| Aider       | `.aider.conf.yml`                                  | No            | Config file; foreground `mem:watch` or `mem:inbox` for A2A       |
+| Antigravity | `AGENTS.md` (native)                               | Unknown       | Research phase                                                   |
+
+### Shared Cross-Vendor Surfaces
+
+LumenFlow stays vendor-agnostic by anchoring on shared repo surfaces first, then layering
+vendor-specific overlays where a client has extra capabilities.
+
+- `AGENTS.md` is the shared instruction baseline. Codex reads it natively, Cursor and Windsurf
+  both support it as a repo instruction surface, and other vendors can usually consume it as plain
+  project guidance.
+- `.agents/skills/` is the shared skills projection surface. Codex and Windsurf can both consume
+  it today, while Claude Code still uses its own `.claude/skills/` overlay.
+- Vendor overlays stay additive: `.claude/agents/`, `.codex/agents/`, `.cursor/rules/`,
+  `.windsurf/rules/`, and similar files add client-specific behavior on top of the shared
+  instruction and skills layers.
+
+### Agent Plugin Distribution
+
+ADR-018 adds plugin distribution as a discoverability on-ramp for Claude Code and Codex. It does
+not replace the repo-level integration surfaces above and it does not replace the Software Delivery
+Pack runtime.
+
+**Current source identity:**
+
+- Canonical bundle: `plugins/lumenflow/`
+- Claude manifest: `plugins/lumenflow/.claude-plugin/plugin.json`
+- Codex manifest: `plugins/lumenflow/.codex-plugin/plugin.json`
+- Claude repo marketplace catalog: `.claude-plugin/marketplace.json`
+- Codex repo marketplace catalog: `.agents/plugins/marketplace.json`
+
+The `lumenflow-dev` repository is the first release train's marketplace source repository. Do not
+create a separate `lumenflow-marketplace` repository unless ADR-018 is amended.
+
+**Namespace and coexistence rules:**
+
+- Canonical skill authoring remains `.lumenflow/skills/<name>/SKILL.md`.
+- Standalone projections keep local names such as `design-first` and `tdd-workflow`.
+- Claude plugin skills are plugin-qualified, for example `/lumenflow:design-first`.
+- Codex plugin prompts should name the installed `lumenflow` plugin or bundled skill through
+  Codex's `@` plugin selection surface; do not invent a Codex slash namespace.
+- Plugin installation must not delete `.claude/skills/`, `.agents/skills/`, or other standalone
+  projections. A future `--plugin-only` cleanup path must be explicit and dry-run-first.
+
+**First-run handoff:**
+
+The plugin can provide skills, hooks, MCP configuration, and first-run guidance. It cannot install
+`.husky/`, GitHub Actions, WU state, conditional gates, co-change gates, or package aliases inside a
+consumer repository. First-run plugin text must direct users to run `npx lumenflow init` for a new
+repo or `pnpm lumenflow:integrate --sync` in an already initialized repo when they want governed
+workflow state, enforcement, gates, and evidence.
+
+**Marketplace preflight:**
+
+- Anthropic official marketplace submission exists today, so a maintainer must confirm or reserve
+  the `lumenflow` plugin name through the Anthropic submission path before marketplace packaging
+  relies on `/lumenflow:*` names.
+- Codex official self-serve publishing is documented as coming later. Until then, Codex readiness
+  targets repo/personal marketplace install with the `lumenflow` id and an official-directory
+  checklist that does not claim undocumented vendor gates.
 
 ---
 
@@ -70,6 +128,7 @@ Cursor is an AI-first code editor built on VS Code.
 
 **Config Files:**
 
+- `AGENTS.md` - Shared repo instructions
 - `.cursor/rules/lumenflow.md` - LumenFlow rules
 
 **Auto-detection:** Environment variables starting with `CURSOR_`
@@ -86,6 +145,8 @@ Windsurf (Codeium) is an AI IDE with agentic capabilities.
 
 **Config Files:**
 
+- `AGENTS.md` - Shared repo instructions
+- `.agents/skills/` - Shared skills discovered by Windsurf
 - `.windsurf/rules/lumenflow.md` - LumenFlow rules
 
 **Auto-detection:** Environment variables starting with `WINDSURF_`
@@ -114,11 +175,14 @@ lumenflow init --client cline
 
 ### OpenAI Codex
 
-Codex reads the AGENTS.md file directly for universal instructions.
+Codex reads shared repo instructions from `AGENTS.md`, shared skills from `.agents/skills/`, and
+vendor-specific subagent overlays from `.codex/agents/`.
 
 **Config Files:**
 
 - `AGENTS.md` - Universal agent instructions (always created)
+- `.agents/skills/` - Shared skills surface
+- `.codex/agents/` - Codex subagent overlays (explicit invocation only)
 
 **Initialize:**
 

package/templates/vendors/claude/.claude/skills/frontend-design/SKILL.md.template

@@ -2,7 +2,7 @@
 name: frontend-design
 description: Create distinctive, production-grade frontend interfaces. Use when building React components, pages, UI features, or when user requests visual/design work.
 version: 1.0.0
-source: docs/operations/_frameworks/lumenflow/lumenflow-agent-capsule.md
+source: {{DOCS_OPERATIONS_PATH}}/_frameworks/lumenflow/lumenflow-agent-capsule.md
 last_updated: {{DATE}}
 allowed-tools: Read, Write, Edit, Bash
 ---

package/templates/vendors/claude/.claude/skills/wu-lifecycle/SKILL.md.template

@@ -65,6 +65,34 @@ pnpm wu:prune --execute     # Clean stale worktrees
 pnpm wu:cleanup --id WU-XXX # After PR merge
 ```
 
+## Coordination Signal Checkpoints
+
+`wu:brief` includes an Inbox Snapshot for the current WU/session when memory is enabled.
+Treat every unread signal surfaced there, at any `mem:checkpoint`, or before `wu:prep`
+as a decision point, not background noise.
+
+Before continuing after an unread signal:
+
+1. Read the signal context.
+2. Decide whether it changes the work, blocks progress, or is not actionable.
+3. Reply, acknowledge, or dismiss it through `mem:signal` / shared memory before moving on.
+
+Do not wait until `wu:done` to inspect coordination traffic. Mid-flight redirects, peer review,
+and orchestrator-worker handoffs depend on agents consuming signals during the WU.
+
+## A2A Signal Hook Delivery
+
+Claude Code sessions with generated LumenFlow hooks receive directed A2A
+`signal:received` events at the next `PostToolUse` boundary. Treat the hook
+payload the same way as an unread `mem:inbox` result:
+
+1. Read the signal message, `intent`, `interrupt_class`, and WU/thread scope.
+2. If `requires_ack: true`, reply on the same thread with `pnpm mem:signal ... --reply-to <signal_id> --intent AGREE` or `--intent REJECT`.
+3. Continue only after the decision is recorded, unless an explicit `wu:prep --allow-unread-signals --reason '<audit reason>'` override is justified.
+
+Non-hook clients still rely on `wu:brief`, `mem:checkpoint`, and explicit
+`mem:inbox` polling until the daemon fallback lands.
+
 ## wu:prep + wu:done Workflow (WU-1223)
 
 **Two-step completion:**