component.yaml reference

This page lists every setting a component can have. To learn what components are and when to use each setting, start with Monorepos and Setting up components.

Where components liveCopy Anchor Link

Each component is a folder in .dmx/components/. The folder's name is the component's id, and the folder holds the component's component.yaml:

.dmx/components/payments/component.yaml

An id uses lowercase letters, digits, - and _, and starts with a letter or a digit. You use it wherever you refer to the component: in another component's depends_on, in a spec's components, in learning tags such as [payments], and in the names of the component's skills and loops, such as payments/refund-check.

A complete exampleCopy Anchor Link

# .dmx/components/payments/component.yaml
description: Payment processing service
paths: ["services/payments/**"]
depends_on: [ledger]
test:
  cmd: make test
  cwd: services/payments
  known_failures:
    - TestSettlementClock          # fails on macOS runners
validators:
  validate: [idempotent_refunds]
ticket:
  jira_project: PAY

description and paths are required. Everything else is optional.

SettingsCopy Anchor Link

descriptionCopy Anchor Link

Required. One line saying what the component is. dmx shows it when it lists components.

pathsCopy Anchor Link

Required. The files that belong to the component. A list of patterns, relative to the root of the repository, written like .gitignore entries:

• ** matches any number of folders, and * and ? match within one folder name;
• a pattern that matches a folder also matches everything inside it;
• a pattern can't contain a .. segment.

paths: ["services/payments/**", "tests/payments/**"]

A file belongs to at most one component. If two components' patterns match the same file, the more specific pattern wins, as in CODEOWNERS: services/payments/sdk/** beats services/payments/**. A file that no component matches is a repo-wide file. See Paths.

depends_onCopy Anchor Link

The ids of the components this component uses. See Dependencies.

depends_on: [ledger]

When one of them changes, this component's tests run too. While working on this component, the agent also reads their memory.

testCopy Anchor Link

The command that runs the component's tests, used instead of the one dmx works out for itself. See How a component's tests are run.

validatorsCopy Anchor Link

Checks that run, in the loops you name, on every ticket that includes the component. They're added to the loop's own validators. See Checks a component adds.

Each entry is either the name of a validator, in which case every check it reports is required, or the same mapping as a validator in loop configuration:

validators:
  validate:
    - no_float_money
    - tool: migration_safety
      timeout_seconds: 300
      checks:
        - name: reversible
          required: true
        - name: no_table_locks
          required: false

Each check is named after the component, such as ledger/reversible. dmx looks for the validator in the component's validators/ folder first, then wherever it looks for the repository's own validators.

ticketCopy Anchor Link

Where tickets for this component are filed by default. The destination must be one of those allowed in .dmx/config.md. See Where the ticket is filed.

What the component's folder holdsCopy Anchor Link

.dmx/components/payments/
├── component.yaml            the component's settings
├── systemPatterns.md         the component's memory: any .md file
├── techContext.md
├── skills/                   optional: skills, named payments/<name>
├── loops/                    optional: loops, named payments/<name>
├── validators/               optional: validators for the component's checks and loops
├── shared-sources.yaml       optional: shared sources for the component
└── shared-sources.lock

The component's skills and loops can be used only on tickets that include the component. A validator named in one of the component's loops runs from its validators/ folder when it's there, with its checks reported as <id>/<check>. See Component skills and loops and per-component shared sources.

Settings in .dmx/config.mdCopy Anchor Link

A few repository-wide settings go with components:

After changing any of these, or a component.yaml, run dmx check. It reports:

• files it can't read;
• unknown or circular depends_on;
• paths that overlap or match nothing;
• components without a test command;
• ticket destinations that aren't allowed.