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.

Note

Omitting software_delivery.agents remains non-breaking. LumenFlow falls back to the current built-in defaults: defaultClient: claude-code, the built-in framework agent roster, and an empty mandatory-agent configuration.

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

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:

1. Add agents.roster when you want to declare a custom or narrowed set of agent names.
2. Add agents.mandatory.names when some of those agents should become enforceable.
3. Add agents.mandatory.triggers when you want code-path-based mandatory-agent detection.
4. Add agents.clients.<client>.agentsDir when a client should resolve agent definitions from a non-default directory.

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.