@lumenflow/cli 5.0.2 → 5.1.0

package/packs/software-delivery/src/config/schemas/lumenflow-config-schema-types.ts

@@ -29,6 +29,11 @@ import {
   DEFAULT_MAX_ESLINT_WARNINGS,
   DEFAULT_MIN_COVERAGE,
 } from '../../constants/gate-constants.js';
+import {
+  AGENT_NAMES,
+  MANDATORY_AGENT_NAMES,
+  MANDATORY_TRIGGERS,
+} from '../../domain/orchestration.constants.js';
 
 const DEFAULT_LAYOUT = DOCS_LAYOUT_PRESETS.simple;
 
@@ -76,7 +81,7 @@ export const DIRECTORIES_DEFAULTS: DirectoriesConfig = {
   initiativesDir: `${DEFAULT_LAYOUT.tasks}/initiatives`,
   backlogPath: `${DEFAULT_LAYOUT.tasks}/backlog.md`,
   statusPath: `${DEFAULT_LAYOUT.tasks}/status.md`,
-  skillsDir: '.claude/skills',
+  skillsDir: '.lumenflow/skills',
   agentsDir: '.claude/agents',
   adrDir: DEFAULT_LAYOUT.adrDir,
   plansDir: `${DEFAULT_LAYOUT.operations}/plans`,
@@ -342,16 +347,35 @@ export const MEMORY_DEFAULTS: MemoryConfig = {
 };
 
 // ---------------------------------------------------------------------------
-// Agents (narrow — only defaultClient, which many cohorts need)
+// Agents
 // ---------------------------------------------------------------------------
 
+export interface MandatoryAgentsConfig {
+  names: string[];
+  triggers: Record<string, string[]>;
+  [extra: string]: unknown;
+}
+
 export interface AgentsConfig {
   defaultClient: string;
+  roster: string[];
+  mandatory: MandatoryAgentsConfig;
   [extra: string]: unknown;
 }
 
+function cloneMandatoryTriggersDefaults(): Record<string, string[]> {
+  return Object.fromEntries(
+    Object.entries(MANDATORY_TRIGGERS).map(([agentName, patterns]) => [agentName, [...patterns]]),
+  );
+}
+
 export const AGENTS_DEFAULTS: AgentsConfig = {
   defaultClient: LUMENFLOW_CLIENT_IDS.CLAUDE_CODE,
+  roster: [...AGENT_NAMES],
+  mandatory: {
+    names: [...MANDATORY_AGENT_NAMES],
+    triggers: cloneMandatoryTriggersDefaults(),
+  },
 };
 
 // ---------------------------------------------------------------------------

package/packs/software-delivery/src/config/workspace-reader.ts

@@ -172,6 +172,30 @@ function mergeSimple<T>(defaults: T, overrides: unknown): T {
   return { ...defaults };
 }
 
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+
+function cloneStringArrayRecord(record: Record<string, string[]>): Record<string, string[]> {
+  return Object.fromEntries(Object.entries(record).map(([key, values]) => [key, [...values]]));
+}
+
+function readStringArrayRecord(value: unknown): Record<string, string[]> {
+  if (!isObjectRecord(value)) {
+    return {};
+  }
+
+  return Object.fromEntries(
+    Object.entries(value).flatMap(([key, entryValue]) =>
+      isStringArray(entryValue) ? [[key, [...entryValue]]] : [],
+    ),
+  );
+}
+
 function mergeTelemetry(overrides: Partial<TelemetryConfig> | undefined): TelemetryConfig {
   if (!overrides) {
     return { methodology: { ...TELEMETRY_DEFAULTS.methodology } };
@@ -189,6 +213,47 @@ function pickEnum<T extends string>(value: unknown, allowed: readonly T[], fallb
     : fallback;
 }
 
+function cloneAgentsDefaults(): AgentsConfig {
+  return {
+    ...AGENTS_DEFAULTS,
+    roster: [...AGENTS_DEFAULTS.roster],
+    mandatory: {
+      ...AGENTS_DEFAULTS.mandatory,
+      names: [...AGENTS_DEFAULTS.mandatory.names],
+      triggers: cloneStringArrayRecord(AGENTS_DEFAULTS.mandatory.triggers),
+    },
+  };
+}
+
+function mergeAgents(overrides: unknown): AgentsConfig {
+  if (!isObjectRecord(overrides)) {
+    return cloneAgentsDefaults();
+  }
+
+  const defaults = cloneAgentsDefaults();
+  const { defaultClient, roster, mandatory: overrideMandatory, ...flatOverrides } = overrides;
+  const mandatoryOverrides = isObjectRecord(overrideMandatory) ? overrideMandatory : {};
+
+  return {
+    ...defaults,
+    ...flatOverrides,
+    defaultClient:
+      typeof defaultClient === 'string' ? defaultClient : AGENTS_DEFAULTS.defaultClient,
+    roster: isStringArray(roster) ? [...roster] : [...AGENTS_DEFAULTS.roster],
+    mandatory: {
+      ...defaults.mandatory,
+      ...mandatoryOverrides,
+      names: isStringArray(mandatoryOverrides['names'])
+        ? [...mandatoryOverrides['names']]
+        : [...AGENTS_DEFAULTS.mandatory.names],
+      triggers: {
+        ...cloneStringArrayRecord(AGENTS_DEFAULTS.mandatory.triggers),
+        ...readStringArrayRecord(mandatoryOverrides['triggers']),
+      },
+    },
+  };
+}
+
 /**
  * Return the fully-typed pack-local `LumenflowConfig` for the workspace rooted
  * at `cwd`.
@@ -230,7 +295,7 @@ export function getConfig(cwd: string): LumenflowConfig {
     memory: mergeSimple<MemoryConfig>(MEMORY_DEFAULTS, section['memory']),
     ui: mergeSimple<UiConfig>(UI_DEFAULTS, section['ui']),
     yaml: mergeSimple<YamlConfig>(YAML_DEFAULTS, section['yaml']),
-    agents: mergeSimple<AgentsConfig>(AGENTS_DEFAULTS, section['agents']),
+    agents: mergeAgents(section['agents']),
     experimental: mergeSimple<ExperimentalConfig>(EXPERIMENTAL_DEFAULTS, section['experimental']),
     cleanup: mergeSimple<CleanupConfig>(CLEANUP_DEFAULTS, section['cleanup']),
     telemetry: mergeTelemetry(section['telemetry'] as Partial<TelemetryConfig> | undefined),
@@ -275,7 +340,7 @@ function cloneDefaults(): LumenflowConfig {
     memory: { ...MEMORY_DEFAULTS },
     ui: { ...UI_DEFAULTS },
     yaml: { ...YAML_DEFAULTS },
-    agents: { ...AGENTS_DEFAULTS },
+    agents: cloneAgentsDefaults(),
     experimental: { ...EXPERIMENTAL_DEFAULTS },
     cleanup: { ...CLEANUP_DEFAULTS },
     telemetry: { methodology: { ...TELEMETRY_DEFAULTS.methodology } },

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

@@ -82,6 +82,32 @@ export const DIRECTORIES = {
   STATUS_PATH: `${DEFAULT_DOCS_PATHS.tasks}/status.md`,
 };
 
+/**
+ * Shared agent/client surface paths.
+ *
+ * Keeps vendor overlay and shared projection roots centralized so runtime code
+ * does not scatter hardcoded path literals through CLI/core packages.
+ */
+export const AGENT_SURFACES = {
+  /** Claude-projected skills directory */
+  CLAUDE_SKILLS_DIR: '.claude/skills',
+
+  /** Claude agent overlay directory */
+  CLAUDE_AGENTS_DIR: '.claude/agents',
+
+  /** Shared cross-vendor projected skills directory */
+  SHARED_SKILLS_DIR: '.agents/skills',
+
+  /** Codex agent overlay directory */
+  CODEX_AGENTS_DIR: '.codex/agents',
+
+  /** Gemini projected skills directory */
+  GEMINI_SKILLS_DIR: '.gemini/skills',
+
+  /** Gemini agent overlay directory */
+  GEMINI_AGENTS_DIR: '.gemini/agents',
+};
+
 /**
  * Build artifact cleanup globs
  *

package/packs/software-delivery/src/domain/orchestration.constants.ts

@@ -47,8 +47,12 @@ export type Lane = (typeof LANES)[number];
  * Known agent names in the orchestration system.
  * Includes both mandatory (Tier 1) and suggested (Tier 2) agents.
  *
- * Note: These are LumenFlow framework agents defined in .claude/agents/.
- * Application-specific agents should be configured separately.
+ * Note: These are the framework's vendor-neutral default aliases. Vendor
+ * overlays may materialize them in different native surfaces, and
+ * application-specific agents should still be configured separately.
+ *
+ * v2 roster refresh: the default set removes `lumenflow-doc-sync` and adds
+ * `initiative-architect`.
  */
 export const AGENT_NAMES = [
   'general-purpose',
@@ -57,12 +61,9 @@ export const AGENT_NAMES = [
   'code-reviewer',
   'bug-triage',
   'lumenflow-enforcer',
-  'lumenflow-doc-sync',
+  'initiative-architect',
 ] as const;
 
-/** Type for agent names */
-export type AgentName = (typeof AGENT_NAMES)[number];
-
 /**
  * Alert severity levels for dashboard display.
  * HIGH = action required immediately
@@ -127,9 +128,6 @@ export type UserChoiceOption = (typeof USER_CHOICE_OPTIONS)[number];
  */
 export const MANDATORY_AGENT_NAMES = [] as const;
 
-/** Type for mandatory agent names */
-export type MandatoryAgentName = (typeof MANDATORY_AGENT_NAMES)[number];
-
 /**
  * Mandatory agent triggers - glob patterns that indicate when agents must be invoked.
  * Uses minimatch patterns (NOT regex) for file path matching.

package/packs/software-delivery/src/domain/orchestration.schemas.ts

@@ -15,7 +15,6 @@
 import { z } from 'zod';
 import {
   LANES,
-  AGENT_NAMES,
   SEVERITY_LEVELS,
   AGENT_RESULT_STATUSES,
   TIMELINE_EVENT_TYPES,
@@ -38,7 +37,7 @@ const LongestRunningSchema = z.object({
  */
 const PendingMandatorySchema = z.object({
   wuId: z.string().min(1),
-  agent: z.enum(AGENT_NAMES),
+  agent: z.string().min(1),
 });
 
 /**

package/packs/software-delivery/src/domain/orchestration.types.ts

@@ -28,13 +28,11 @@ import type {
 // Re-export constant-derived types for convenience
 export type {
   Lane,
-  AgentName,
   SeverityLevel,
   AgentResultStatus,
   TimelineEventType,
   EventSeverityLevel,
   UserChoiceOption,
-  MandatoryAgentName,
 } from './orchestration.constants.js';
 
 // Re-export const values as well

package/packs/software-delivery/src/state/wu-paths.ts

@@ -67,7 +67,7 @@ const FALLBACK_DIRECTORIES: WorkspaceDirectories = {
   initiativesDir: 'docs/operations/tasks/initiatives',
   backlogPath: 'docs/operations/tasks/backlog.md',
   statusPath: 'docs/operations/tasks/status.md',
-  skillsDir: '.claude/skills',
+  skillsDir: '.lumenflow/skills',
   agentsDir: '.claude/agents',
   adrDir: 'docs/adr',
   plansDir: 'docs/operations/plans',

package/templates/core/AGENTS.md.template

@@ -204,14 +204,18 @@ 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 |
-| OpenAI Codex | `.codex/skills/` or repo `skills/`      | `/skills`, `$<name>` mention, or implicit                |
-| Cursor       | `.cursor/rules/` + agent skills         | `/skills` or auto-discovery                              |
-| Windsurf     | `.windsurf/rules/` + Cascade skills     | Auto-discovery; workflows via `/<workflow-name>`         |
-| Aider        | `CONVENTIONS.md`                        | `/read CONVENTIONS.md` or `aider --read CONVENTIONS.md`  |
-| Cline        | `.clinerules`                           | Auto-loaded                                              |
+| 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                                                            |
+
+Shared cross-vendor surfaces: `AGENTS.md` and `.agents/skills/`.
+Vendor-specific overlays: `.claude/agents/`, `.codex/agents/`, `.cursor/rules/`, and `.windsurf/rules/`.
+For Codex specifically, `.codex/agents/*.toml` are explicit-only subagent overlays; Codex will not auto-match them by description.
 
 A skill named in prose does nothing — load it through the vendor's invocation before the work it covers. See [LUMENFLOW.md "Skills & Agents"](LUMENFLOW.md#skills--agents) for the canonical skill list.
 

package/templates/core/LUMENFLOW.md.template

@@ -761,15 +761,20 @@ For vendor-specific setup details and per-vendor quirks, see:
 
 ### Agents
 
-Pre-configured agent definitions in `.claude/agents/`:
+Recommended framework roster (vendor-neutral aliases):
 
-| Agent             | Purpose                    |
-| ----------------- | -------------------------- |
-| `general-purpose` | Standard WU implementation |
-| `lumenflow-pm`    | Backlog & lifecycle        |
-| `test-engineer`   | TDD, coverage              |
-| `code-reviewer`   | Quality checks             |
-| `bug-triage`      | Bug classification         |
+| Agent                  | Purpose                               |
+| ---------------------- | ------------------------------------- |
+| `general-purpose`      | Standard WU implementation            |
+| `lumenflow-pm`         | Backlog & lifecycle                   |
+| `test-engineer`        | TDD, coverage                         |
+| `code-reviewer`        | Quality checks                        |
+| `bug-triage`           | Bug classification                    |
+| `lumenflow-enforcer`   | Workflow compliance and gates         |
+| `initiative-architect` | Initiative planning and decomposition |
+
+Client-specific overlays may implement these aliases in different native surfaces such as
+`.claude/agents/`, `.codex/agents/`, or vendor rule/config directories.
 
 Generate handoff prompts (prompt-only, execution is a separate step): `pnpm wu:brief --id WU-XXX --client <client>`
 Record explicit delegation lineage when needed: `pnpm wu:delegate --id WU-XXX --parent-wu WU-YYY --client <client>`
@@ -797,5 +802,5 @@ 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
-- [Skills Index](.claude/skills/INDEX.md)
+- [Skills Index](.lumenflow/skills/INDEX.md)
 - [Agents README](.claude/agents/README.md)

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

@@ -146,6 +146,10 @@ 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:
 
@@ -214,6 +218,7 @@ 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