workspace.yaml agents

The software_delivery.agents block configures which agent client LumenFlow prefers, which agent names are considered part of the workspace roster, and which of those agents become mandatory for matching code paths.

Shape

software_delivery:
  agents:
    defaultClient: claude-code
    roster:
      - general-purpose
      - lumenflow-pm
      - test-engineer
      - code-reviewer
      - bug-triage
      - lumenflow-enforcer
      - initiative-architect
    mandatory:
      names: []
      triggers: {}
    clients:
      codex-cli:
        agentsDir: .agents/agents

Fields

`agents.defaultClient`

Preferred client ID when a command needs an agent client and the caller did not pass one explicitly.

Type: string
Default: claude-code

`agents.roster`

The workspace-level list of agent names the orchestration surface should treat as valid. When you omit this field, LumenFlow uses the built-in framework roster:

general-purpose
lumenflow-pm
test-engineer
code-reviewer
bug-triage
lumenflow-enforcer
initiative-architect
Type: string[]
Default: the built-in agent roster above

`agents.mandatory.names`

Subset of agents.roster that may be enforced as mandatory when a matching trigger fires.

Type: string[]
Default: []

`agents.mandatory.triggers`

Maps mandatory agent names to glob patterns. If a WU touches a matching path, that agent becomes mandatory for the workflow surfaces that consume mandatory-agent rules.

Type: Record<string, string[]>
Default: {}

Example:

software_delivery:
  agents:
    roster:
      - custom-security-reviewer
    mandatory:
      names:
        - custom-security-reviewer
      triggers:
        custom-security-reviewer:
          - auth/**
          - supabase/migrations/**

`agents.clients.<client>.agentsDir`

Optional per-client override for where agent definition files live. This is separate from the workspace roster itself, but it is commonly updated alongside agents.roster when you add a new client-specific agent surface.

Type: string
Default: inherits the global directory default for that client

`agents.clients.<client>.capabilities`

Runtime capability descriptor for a client (INIT-078). This block replaces the hardcoded client allow-lists that previously gated native signal delivery, agent overlay directories, and brief rendering. It answers capability questions (“does this client have a native signal hook?”) instead of membership questions (“is this client in the blessed list?”).

Type: object
Default: a known-client table ships in code with accurate values for claude-code, codex-cli, gemini-cli, cursor, and windsurf.

Fields (all optional; omitted fields fall back to the in-code default for that client):

Field	Type	Meaning
`native_signal_hooks`	`boolean`	Client can deliver A2A signals without a CLI round-trip.
`agents_dir`	`string`	Directory the client reads agent definitions from.
`settings_projection`	enum	How LumenFlow projects client settings.
`enforcement_hooks`	`boolean`	Client supports generated enforcement hooks.
`brief_renderer`	`markdown` \| `claude-code`	Which brief projection the `wu:brief` renderer targets.

software_delivery:
  agents:
    clients:
      my-byok-agent:
        capabilities:
          native_signal_hooks: false
          brief_renderer: markdown

BYOK clients are first-class. Any client id — not just the blessed five — is accepted across the lifecycle (wu:claim, wu:brief, agent:session, orchestrate:initiative, …). An unknown client id resolves to a conservative fallback descriptor with every enhancement off (native_signal_hooks: false, brief_renderer: markdown, no agents_dir). The conservative default cannot suppress telemetry — a BYOK client still emits all CLI-borne telemetry by virtue of running the standard commands — it only declines optional vendor-hook accelerators. The brief renderer therefore defaults to the portable markdown projection, and signal delivery falls back to the CLI / mem:watch path when no native hook is available.

Defaults And Partial Overrides

Nested agent config merges with defaults instead of replacing the whole structure. For example, this partial override keeps the built-in roster and default client while only adding trigger rules:

software_delivery:
  agents:
    mandatory:
      triggers:
        custom-agent:
          - auth/**

Likewise, setting only mandatory.names no longer removes the default mandatory.triggers object.

Migration

If your workspace previously only used:

software_delivery:
  agents:
    defaultClient: codex-cli

you do not need to change anything. That configuration still works.

Add the new fields only when you need them:

Add agents.roster when you want to declare a custom or narrowed set of agent names.
Add agents.mandatory.names when some of those agents should become enforceable.
Add agents.mandatory.triggers when you want code-path-based mandatory-agent detection.
Add agents.clients.<client>.agentsDir when a client should resolve agent definitions from a non-default directory.
Add agents.clients.<client>.capabilities only when you need to override the in-code defaults for a known client or describe a BYOK client’s runtime surfaces. Unknown clients work without it via the conservative fallback.

Validation Rules

The authoritative schema enforces two cross-field rules:

Every name in agents.mandatory.names must also appear in agents.roster.
Every key in agents.mandatory.triggers must also appear in agents.mandatory.names.

Those rules keep the roster, mandatory list, and trigger map aligned as you customize the workspace.