@lumenflow/cli 5.3.2 → 5.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "5.3.2",
+  "version": "5.5.0",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -98,6 +98,7 @@
     "lumenflow-validate": "./dist/validate.js",
     "mem-checkpoint": "./dist/mem-checkpoint.js",
     "mem-cleanup": "./dist/mem-cleanup.js",
+    "mem-converged": "./dist/mem-converged.js",
     "mem-context": "./dist/mem-context.js",
     "mem-create": "./dist/mem-create.js",
     "mem-delete": "./dist/mem-delete.js",
@@ -111,6 +112,7 @@
     "mem-start": "./dist/mem-start.js",
     "mem-summarize": "./dist/mem-summarize.js",
     "mem-triage": "./dist/mem-triage.js",
+    "mem-watch": "./dist/mem-watch.js",
     "metrics": "./dist/metrics-cli.js",
     "metrics-snapshot": "./dist/metrics-snapshot.js",
     "onboard": "./dist/onboard.js",
@@ -198,16 +200,16 @@
     "xstate": "^5.28.0",
     "yaml": "^2.8.2",
     "zod": "^4.3.6",
-    "@lumenflow/agent": "5.3.2",
-    "@lumenflow/control-plane-sdk": "5.3.2",
-    "@lumenflow/host": "^5.3.2",
-    "@lumenflow/initiatives": "5.3.2",
-    "@lumenflow/kernel": "5.3.2",
-    "@lumenflow/metrics": "5.3.2",
-    "@lumenflow/memory": "5.3.2",
-    "@lumenflow/packs-agent-runtime": "^5.3.2",
-    "@lumenflow/core": "5.3.2",
-    "@lumenflow/packs-software-delivery": "^5.3.2"
+    "@lumenflow/agent": "5.5.0",
+    "@lumenflow/host": "^5.5.0",
+    "@lumenflow/control-plane-sdk": "5.5.0",
+    "@lumenflow/initiatives": "5.5.0",
+    "@lumenflow/core": "5.5.0",
+    "@lumenflow/kernel": "5.5.0",
+    "@lumenflow/packs-agent-runtime": "^5.5.0",
+    "@lumenflow/metrics": "5.5.0",
+    "@lumenflow/memory": "5.5.0",
+    "@lumenflow/packs-software-delivery": "^5.5.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.18",

package/packs/agent-runtime/auto-session-integration.ts

@@ -83,6 +83,10 @@ interface SessionFileData {
   /** ADR-014 extension 2 — which skill bundle the agent identifies as carrying (WU-2754). */
   specialty_profile?: string;
   display_name?: string;
+  /** Stable explicit A2A reader identity. Format hint: <owner>:<role>:<purpose>. */
+  agent_identity?: string;
+  /** Reserved cloud workspace/tenant scope slot; unused by local runtime. */
+  tenant_id?: string;
   /** ADR-014 extension 2 — parent delegation registry reference (WU-2754). */
   delegation_id?: string;
 }
@@ -455,6 +459,10 @@ interface StartSessionOptions {
   /** ADR-014 specialty_profile for this session (e.g. 'delivery'). */
   specialtyProfile?: string;
   displayName?: string;
+  /** Explicit stable A2A reader identity. Format hint: <owner>:<role>:<purpose>. */
+  agentIdentity?: string;
+  /** Reserved cloud workspace/tenant scope slot; unused by local runtime. */
+  tenantId?: string;
   /** Parent delegation-registry record reference (dlg-XXXX). */
   delegationId?: string;
 }
@@ -511,6 +519,8 @@ export async function startSessionForWU(options: StartSessionOptions): Promise<S
     lifecycleRole,
     specialtyProfile,
     displayName,
+    agentIdentity,
+    tenantId,
     delegationId,
   } = options;
 
@@ -542,6 +552,8 @@ export async function startSessionForWU(options: StartSessionOptions): Promise<S
     lifecycle_role: lifecycleRole,
     specialty_profile: specialtyProfile,
     display_name: displayName,
+    agent_identity: agentIdentity,
+    tenant_id: tenantId,
     delegation_id: delegationId,
   });
   const resolvedDisplayName = roleAxes.display_name ?? acquireDisplayName(workspaceRoot, sessionId);
@@ -564,6 +576,8 @@ export async function startSessionForWU(options: StartSessionOptions): Promise<S
     lifecycle_role: roleAxes.lifecycle_role,
     specialty_profile: roleAxes.specialty_profile,
     display_name: resolvedDisplayName,
+    ...(roleAxes.agent_identity ? { agent_identity: roleAxes.agent_identity } : {}),
+    ...(roleAxes.tenant_id ? { tenant_id: roleAxes.tenant_id } : {}),
     ...(roleAxes.delegation_id ? { delegation_id: roleAxes.delegation_id } : {}),
   };
 

package/packs/agent-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/packs-agent-runtime",
-  "version": "5.3.2",
+  "version": "5.5.0",
   "description": "Agent runtime pack scaffold for LumenFlow — governed model-turn execution, pack config, and provider capability baselines",
   "keywords": [
     "lumenflow",

package/packs/agent-runtime/session-schema.ts

@@ -70,6 +70,7 @@ export const DISPLAY_NAME_POOL_RELATIVE_PATH = '.lumenflow/agents/display-name-p
 export const DISPLAY_NAME_RESERVATIONS_RELATIVE_PATH =
   '.lumenflow/state/display-name-reservations.jsonl';
 export const DISPLAY_NAME_RESERVATION_TTL_HOURS = 12;
+export const AGENT_IDENTITY_MIN_LENGTH = 3;
 
 /** Regex for delegation_id references back into delegation registry. */
 export const DELEGATION_ID_PATTERN = /^dlg-[0-9a-f]{4}$/;
@@ -93,6 +94,14 @@ export const SessionRoleAxesSchema = z.object({
     .optional(),
 });
 
+const AgentIdentitySchema = z
+  .string()
+  .trim()
+  .min(AGENT_IDENTITY_MIN_LENGTH, {
+    message: `agent_identity must be at least ${AGENT_IDENTITY_MIN_LENGTH} characters`,
+  });
+const TenantIdSchema = z.string().trim().min(1, { message: 'tenant_id must be non-empty' });
+
 /**
  * Base session schema — shared fields across v1 and v2.
  *
@@ -104,6 +113,8 @@ const SessionRecordBaseSchema = z.object({
   session_id: z.string().min(1),
   wu_id: z.string().min(1),
   started: z.string().min(1),
+  agent_identity: AgentIdentitySchema.optional(),
+  tenant_id: TenantIdSchema.optional(),
 });
 
 /**
@@ -172,11 +183,15 @@ export function withV2RoleDefaults(input: {
   specialty_profile?: string | null;
   display_name?: string | null;
   delegation_id?: string | null;
+  agent_identity?: string | null;
+  tenant_id?: string | null;
 }): {
   lifecycle_role: string;
   specialty_profile: string;
   display_name?: string;
   delegation_id?: string;
+  agent_identity?: string;
+  tenant_id?: string;
 } {
   const lifecycle_role =
     typeof input.lifecycle_role === 'string' && input.lifecycle_role.trim().length > 0
@@ -194,11 +209,14 @@ export function withV2RoleDefaults(input: {
     typeof input.display_name === 'string' && input.display_name.trim().length > 0
       ? input.display_name.trim()
       : undefined;
+  const identityFields = normalizeOptionalSessionIdentityFields(input);
   const out: {
     lifecycle_role: string;
     specialty_profile: string;
     display_name?: string;
     delegation_id?: string;
+    agent_identity?: string;
+    tenant_id?: string;
   } = {
     lifecycle_role,
     specialty_profile,
@@ -209,6 +227,32 @@ export function withV2RoleDefaults(input: {
   if (delegation_id) {
     out.delegation_id = delegation_id;
   }
+  if (identityFields.agent_identity) {
+    out.agent_identity = identityFields.agent_identity;
+  }
+  if (identityFields.tenant_id) {
+    out.tenant_id = identityFields.tenant_id;
+  }
+  return out;
+}
+
+export function normalizeOptionalSessionIdentityFields(input: {
+  agent_identity?: string | null;
+  tenant_id?: string | null;
+}): {
+  agent_identity?: string;
+  tenant_id?: string;
+} {
+  const out: {
+    agent_identity?: string;
+    tenant_id?: string;
+  } = {};
+  if (typeof input.agent_identity === 'string' && input.agent_identity.trim().length > 0) {
+    out.agent_identity = AgentIdentitySchema.parse(input.agent_identity);
+  }
+  if (typeof input.tenant_id === 'string' && input.tenant_id.trim().length > 0) {
+    out.tenant_id = TenantIdSchema.parse(input.tenant_id);
+  }
   return out;
 }
 

package/packs/sidekick/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/packs-sidekick",
-  "version": "5.3.2",
+  "version": "5.5.0",
   "description": "Sidekick personal assistant pack for LumenFlow — 16 tools for task management, typed memory, channels, routines, and audit",
   "keywords": [
     "lumenflow",

package/packs/software-delivery/manifest.ts

@@ -140,6 +140,7 @@ const MEM_DELETE_TOOL_ENTRY = 'tool-impl/memory-tools.ts#memDeleteTool';
 const MEM_EXPORT_TOOL_ENTRY = 'tool-impl/memory-tools.ts#memExportTool';
 const MEM_INBOX_TOOL_ENTRY = 'tool-impl/memory-tools.ts#memInboxTool';
 const MEM_SIGNAL_TOOL_ENTRY = 'tool-impl/memory-tools.ts#memSignalTool';
+const MEM_CONVERGED_TOOL_ENTRY = 'tool-impl/memory-tools.ts#memConvergedTool';
 const MEM_SUMMARIZE_TOOL_ENTRY = 'tool-impl/memory-tools.ts#memSummarizeTool';
 const MEM_TRIAGE_TOOL_ENTRY = 'tool-impl/memory-tools.ts#memTriageTool';
 const MEM_RECOVER_TOOL_ENTRY = 'tool-impl/memory-tools.ts#memRecoverTool';
@@ -245,6 +246,7 @@ const TOOL_PERMISSIONS = {
   'wu:validate': 'read',
   'mem:checkpoint': 'write',
   'mem:cleanup': 'write',
+  'mem:converged': 'read',
   'mem:context': 'read',
   'mem:create': 'write',
   'mem:delete': 'write',
@@ -371,6 +373,7 @@ const TOOL_ENTRY_OVERRIDES: Partial<Record<ToolName, string>> = {
   'mem:export': MEM_EXPORT_TOOL_ENTRY,
   'mem:inbox': MEM_INBOX_TOOL_ENTRY,
   'mem:signal': MEM_SIGNAL_TOOL_ENTRY,
+  'mem:converged': MEM_CONVERGED_TOOL_ENTRY,
   'mem:summarize': MEM_SUMMARIZE_TOOL_ENTRY,
   'mem:triage': MEM_TRIAGE_TOOL_ENTRY,
   'mem:recover': MEM_RECOVER_TOOL_ENTRY,

package/packs/software-delivery/manifest.yaml

@@ -244,6 +244,13 @@ tools:
     entry: tool-impl/memory-tools.ts#memCleanupTool
     permission: write
     required_scopes: *softwareDeliveryWriteScopes
+  - name: mem:converged
+    entry: tool-impl/memory-tools.ts#memConvergedTool
+    permission: read
+    required_scopes:
+      - type: path
+        pattern: '**'
+        access: read
   - name: mem:context
     entry: tool-impl/memory-tools.ts#memContextTool
     permission: read

package/packs/software-delivery/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/packs-software-delivery",
-  "version": "5.3.2",
+  "version": "5.5.0",
   "description": "Software delivery pack for LumenFlow — work units, gates, lanes, initiatives, and agent coordination",
   "keywords": [
     "lumenflow",

package/packs/software-delivery/src/constants/wu-cli-constants.ts

@@ -87,6 +87,10 @@ export const SCRIPTS = {
   LINT: 'lint',
   TEST: 'test',
   TEST_UNIT: 'test:unit',
+  /** WU-2927: opt-in local-prep integration-test gate script */
+  TEST_INTEGRATION: 'test:integration',
+  /** WU-2927: opt-in local-prep e2e-smoke gate script */
+  TEST_E2E: 'test:e2e',
   BUILD: 'build',
   FORMAT: 'format',
   FORMAT_CHECK: 'format:check',
@@ -137,6 +141,10 @@ export const GATE_NAMES = {
   LANE_HEALTH: 'lane-health',
   /** WU-1315: Onboarding smoke test (init + wu:create validation) */
   ONBOARDING_SMOKE_TEST: 'onboarding-smoke-test',
+  /** WU-2927: Opt-in local-prep build gate (wraps SCRIPTS.BUILD) */
+  BUILD: 'build',
+  /** WU-2927: Opt-in local-prep Playwright smoke gate */
+  E2E_SMOKE: 'e2e-smoke',
 };
 
 /**
@@ -159,6 +167,10 @@ export const GATE_COMMANDS = {
   TIERED_TEST: 'tiered-test',
   /** WU-1315: Triggers onboarding smoke test */
   ONBOARDING_SMOKE_TEST: 'onboarding-smoke-test',
+  /** WU-2927: Triggers opt-in local-prep build gate */
+  BUILD: 'build-gate',
+  /** WU-2927: Triggers opt-in local-prep e2e-smoke gate */
+  E2E_SMOKE: 'e2e-smoke-gate',
 };
 
 /**

package/packs/software-delivery/tool-impl/memory-tools.ts

@@ -16,6 +16,7 @@ const MEMORY_TOOLS = {
   MEM_EXPORT: 'mem:export',
   MEM_INBOX: 'mem:inbox',
   MEM_SIGNAL: 'mem:signal',
+  MEM_CONVERGED: 'mem:converged',
   MEM_SUMMARIZE: 'mem:summarize',
   MEM_TRIAGE: 'mem:triage',
   MEM_RECOVER: 'mem:recover',
@@ -35,6 +36,7 @@ const MEMORY_TOOL_ERROR_CODES: Record<MemoryToolName, string> = {
   'mem:export': 'MEM_EXPORT_ERROR',
   'mem:inbox': 'MEM_INBOX_ERROR',
   'mem:signal': 'MEM_SIGNAL_ERROR',
+  'mem:converged': 'MEM_CONVERGED_ERROR',
   'mem:summarize': 'MEM_SUMMARIZE_ERROR',
   'mem:triage': 'MEM_TRIAGE_ERROR',
   'mem:recover': 'MEM_RECOVER_ERROR',
@@ -55,6 +57,7 @@ const MEMORY_TOOL_COMMANDS: Record<
   'mem:export': RUNTIME_CLI_COMMANDS.MEM_EXPORT,
   'mem:inbox': RUNTIME_CLI_COMMANDS.MEM_INBOX,
   'mem:signal': RUNTIME_CLI_COMMANDS.MEM_SIGNAL,
+  'mem:converged': RUNTIME_CLI_COMMANDS.MEM_CONVERGED,
   'mem:summarize': RUNTIME_CLI_COMMANDS.MEM_SUMMARIZE,
   'mem:triage': RUNTIME_CLI_COMMANDS.MEM_TRIAGE,
   'mem:recover': RUNTIME_CLI_COMMANDS.MEM_RECOVER,
@@ -338,6 +341,18 @@ export async function memInboxTool(input: unknown): Promise<ToolOutput> {
   if (lane) {
     args.push('--lane', lane);
   }
+  const reader = toStringValue(parsed.for);
+  if (reader) {
+    args.push('--for', reader);
+  }
+  const thread = toStringValue(parsed.thread);
+  if (thread) {
+    args.push('--thread', thread);
+  }
+  const intent = toStringValue(parsed.intent);
+  if (intent) {
+    args.push('--intent', intent);
+  }
 
   return executeMemoryTool(MEMORY_TOOLS.MEM_INBOX, args);
 }
@@ -354,7 +369,47 @@ export async function memSignalTool(input: unknown): Promise<ToolOutput> {
     return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
   }
 
-  return executeMemoryTool(MEMORY_TOOLS.MEM_SIGNAL, [message, '--wu', wu]);
+  const args = [message, '--wu', wu];
+  const to = toStringValue(parsed.to);
+  if (to) {
+    args.push('--to', to);
+  }
+  const thread = toStringValue(parsed.thread);
+  if (thread) {
+    args.push('--thread', thread);
+  }
+  const replyTo = toStringValue(parsed.reply_to);
+  if (replyTo) {
+    args.push('--reply-to', replyTo);
+  }
+  const intent = toStringValue(parsed.intent);
+  if (intent) {
+    args.push('--intent', intent);
+  }
+  const interrupt = toStringValue(parsed.interrupt);
+  if (interrupt) {
+    args.push('--interrupt', interrupt);
+  }
+  if (parsed.requires_ack === true) {
+    args.push('--requires-ack');
+  }
+
+  return executeMemoryTool(MEMORY_TOOLS.MEM_SIGNAL, args);
+}
+
+export async function memConvergedTool(input: unknown): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const thread = toStringValue(parsed.thread);
+  if (!thread) {
+    return createMissingParameterOutput('thread is required');
+  }
+
+  const args = ['--thread', thread];
+  if (parsed.quiet === true) {
+    args.push('--quiet');
+  }
+
+  return executeMemoryTool(MEMORY_TOOLS.MEM_CONVERGED, args);
 }
 
 export async function memSummarizeTool(input: unknown): Promise<ToolOutput> {

package/packs/software-delivery/tool-impl/runtime-cli-adapter.ts

@@ -47,6 +47,7 @@ export const RUNTIME_CLI_COMMANDS = {
   MEM_DELETE: 'mem-delete',
   MEM_EXPORT: 'mem-export',
   MEM_INBOX: 'mem-inbox',
+  MEM_CONVERGED: 'mem-converged',
   MEM_INIT: 'mem-init',
   MEM_READY: 'mem-ready',
   MEM_RECOVER: 'mem-recover',

package/templates/core/AGENTS.md.template

@@ -1,3 +1,5 @@
+<!-- LUMENFLOW:START -->
+
 # Universal Agent Instructions
 
 **Last updated:** {{DATE}}
@@ -87,6 +89,44 @@ pnpm mem:checkpoint --wu WU-XXXX --note '<progress>' --next-steps '<what is next
 
 **Shell-quoting footgun:** always **single-quote** the `--title` value. Bash expands `$var`, `$0`, backticks, and `!hist` inside double-quoted strings, silently corrupting prose containing prices (`$49`), positional refs, or exclamation marks. See [Memory section in LUMENFLOW.md](LUMENFLOW.md#memory-shared-vs-vendor-personal) for the full mem:\* contract.
 
+### Agent-to-Agent Coordination
+
+The shared memory signal layer now speaks the exported `A2A.V1` contract from
+`@lumenflow/control-plane-sdk/a2a`. Local JSONL, generated Claude hooks, and
+`mem:watch` are adapters; lumenflow.cloud uses the same contract over hosted
+tenant/workspace transport (`workspace_id` is optional locally and required in
+hosted buses).
+
+Use stable identities when a role should keep receipt state across restarts:
+
+```bash
+pnpm agent:session --agent-identity codex:implementer:init-066 --wu WU-XXXX
+pnpm mem:signal 'approve this boundary' --wu WU-XXXX --to claude:reviewer:init-066 --intent PROPOSE --requires-ack
+pnpm mem:inbox --for codex:implementer:init-066
+```
+
+Signals addressed with `--to` persist canonical `recipients[]`; legacy
+`target_agent` is only a read-compatible single-recipient alias. Receipts are
+per reader identity, so one agent reading a signal does not hide it from another
+recipient. Threads and `INFO|PROPOSE|COUNTER|AGREE|REJECT` intents make
+coordination decisions machine-readable, `requires_ack` expects a same-thread
+`AGREE` or `REJECT`, and interrupt classes are
+`advisory|priority|urgent` with `soon|immediate` accepted as compatibility
+aliases.
+
+Claude Code receives addressed `signal:received` events through generated
+`PostToolUse` hooks. Other clients should run the daemon fallback in a side
+terminal when they need active delivery:
+
+```bash
+pnpm mem:watch --session <session_id|display_name|agent_identity>
+```
+
+Before `mem:checkpoint`, `wu:prep`, or a handoff, unread directed signals are a
+decision point. Read and ACK/REJECT them before continuing, or use
+`pnpm wu:prep --allow-unread-signals --reason '<audit reason>'` only when the
+override is intentional and auditable.
+
 ### Before wu:done
 
 ```bash
@@ -152,7 +192,45 @@ For detailed troubleshooting, see [troubleshooting-wu-done.md]({{DOCS_ONBOARDING
 
 1. **Fit-For-Surface Verification**: Choose the least brittle verification that gives strong confidence. Prefer TDD for runtime logic when policy requires it; avoid brittle UI implementation-detail tests.
 2. **Worktree Discipline**: After `wu:claim`, work ONLY in the worktree
-3. **Gates Before Done**: Run `pnpm gates` before `wu:done`
+3. **Gates Before Done**: Run `pnpm gates` before `wu:done`. Per-gate skip
+   (`--skip-gate <name>`, repeatable) is the preferred bypass surface as of
+   WU-2925; legacy `--skip-gates` is 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 via
+   `software_delivery.gates.overrides.<gate_id>.skippable=true` may be skipped.
+   Both flags require `--reason` and `--fix-wu`.
+
+   **Safety-critical gates (NEVER skippable, no override):** `format`, `lint`,
+   `typecheck`, `co-change`, `spec:linter`, `claim-validation`,
+   `unread-directed-signal`, `invariants`, `safety-critical-test`. To narrow
+   their reach without flipping the default, set
+   `software_delivery.gates.overrides.<gate_id>.applicability_paths` to a
+   glob list — never flip `skippable` on these.
+
+   **`GateResult` state legend (WU-2926).** Each gate produces one of six
+   discriminated `GateResult` states with stable glyphs:
+   - `passed` ✅ — gate ran successfully
+   - `failed` ❌ — gate ran and failed (or applicable + missing + skippable + `'fail'`)
+   - `skipped-by-agent` ⏭ — explicit `--skip-gate <name>` (audit `source: 'agent'`)
+   - `skipped-auto-not-applicable` ⊘ — gate doesn't apply to this change set
+   - `skipped-auto-missing-prereq` ⊘ — applicable + missing prereq + skippable + auto-skip
+   - `blocked-missing-prereq` 🚫 — applicable + missing prereq + `skippable: false`
+     (silent-bypass guard; exits non-zero, cannot be `--skip-gate`'d). Override
+     per-repo via `software_delivery.gates.overrides.<gate_id>.skippable=true`
+     only when the missing prerequisite is genuinely environmental.
+
+   Auto-skip + blocked states write audit NDJSON with the discriminated
+   `source` field; CFR only counts `source: 'agent'` rows. Public reference:
+   [Gates Reference](https://lumenflow.dev/reference/gates).
+
+   **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 that previously only ran
+   in CI. All three are `skippable: true` and on the per-gate skip allow-list.
+   See [LUMENFLOW.md gates section](LUMENFLOW.md#extended-local-prep-profile-wu-2927)
+   for the schema and latency budget.
+
 4. **Never Bypass Hooks**: No `--no-verify`
 5. **Vendor-Agnostic Dirty-Main Guard**: `wu:prep` and `wu:done` hard-block when main has non-allowlisted dirty files during worktree WUs (including MCP/tool-originated writes). `branch-pr` mode is exempt.
 6. **Docs Parity For Behavior Changes**: If you change LumenFlow behavior or workflow guidance, update internal docs, Starlight docs, or both as appropriate. Generated reference docs do not cover narrative behavior changes by themselves.
@@ -204,14 +282,24 @@ LumenFlow enforces safety at the repository level via git wrappers and hooks. Fo
 
 This file provides universal guidance for all AI agents. LumenFlow skills live in `.lumenflow/skills/` as `SKILL.md` files and are projected to each vendor via `pnpm lumenflow:integrate --client <x>`.
 
-| Vendor       | Skill / rules surface                               | Invocation                                                             |
-| ------------ | --------------------------------------------------- | ---------------------------------------------------------------------- |
-| Claude Code  | `.claude/skills/` + `.claude/CLAUDE.md`             | `Skill` tool call, or `/skill <name>` in interactive CLI               |
+Agent plugins are a discovery and invocation on-ramp, not a replacement for repo-level LumenFlow
+integration. **Plugin packaging is scoped under INIT-065 and not yet shipped as of 5.4.0** — the
+guidance below applies once the packaging WUs land. If a plugin is installed alongside standalone
+projections, use the surface-specific name: standalone skills keep local names such as
+`design-first`, Claude plugin skills use names such as `/lumenflow:design-first`, and Codex plugin
+use should select the installed `lumenflow` plugin or bundled skill through Codex's `@` plugin
+selection surface. Plugin installation must not delete `.claude/skills/` or `.agents/skills/`, and
+governed repo enforcement still requires `npx lumenflow init`, `pnpm lumenflow:integrate`, or
+`pnpm lumenflow:integrate --sync`.
+
+| Vendor       | Skill / rules surface                              | Invocation                                                             |
+| ------------ | -------------------------------------------------- | ---------------------------------------------------------------------- |
+| Claude Code  | `.claude/skills/` + `.claude/CLAUDE.md`            | `Skill` tool call, or `/skill <name>` in interactive CLI               |
 | OpenAI Codex | `AGENTS.md` + `.agents/skills/` + `.codex/agents/` | `/skills`, `$<name>` mention, implicit skills, explicit subagent usage |
-| Cursor       | `.cursor/rules/` + `.agents/skills/`                | `/skills` or auto-discovery                                            |
-| Windsurf     | `.windsurf/rules/` + `.agents/skills/`              | Auto-discovery; workflows via `/<workflow-name>`                       |
-| Aider        | `CONVENTIONS.md`                                    | `/read CONVENTIONS.md` or `aider --read CONVENTIONS.md`                |
-| Cline        | `.clinerules`                                       | Auto-loaded                                                            |
+| Cursor       | `.cursor/rules/` + `.agents/skills/`               | `/skills` or auto-discovery                                            |
+| Windsurf     | `.windsurf/rules/` + `.agents/skills/`             | Auto-discovery; workflows via `/<workflow-name>`                       |
+| Aider        | `CONVENTIONS.md`                                   | `/read CONVENTIONS.md` or `aider --read CONVENTIONS.md`                |
+| Cline        | `.clinerules`                                      | Auto-loaded                                                            |
 
 Shared cross-vendor surfaces: `AGENTS.md` and `.agents/skills/`.
 Vendor-specific overlays: `.claude/agents/`, `.codex/agents/`, `.cursor/rules/`, and `.windsurf/rules/`.
@@ -315,3 +403,5 @@ pnpm wu:brief --id WU-XXX --client codex-cli
 
 Recovery files contain your last checkpoint, acceptance criteria, code paths, and changed files.
 Always save checkpoints before long operations: `pnpm mem:checkpoint "progress note" --wu WU-XXX`
+
+<!-- LUMENFLOW:END -->