Configuration

The configuration lives in <home>/config.yaml, where <home> is the data home: ~/.theway by default, or the folder chosen at install (with --home or the install question) or set by THEWAY_HOME (see Locations; theway path prints it). Install writes it once and keeps your copy on later installs; the shipped version is always written to <home>/config.default.yaml, so you can compare the two.

A project can have its own <home>/projects/<key>/config.yaml, where <key> is the project key that theway project prints. It takes the same keys as the global file and can override any of them; install never writes it. The commands and the shipped prompts read it through theway context. When the global config.yaml is missing, it fails and the commands tell you to run npx --yes @pixelfactoryio/theway@latest install, then /reload-plugins. The standards keys reach the commands through the standards list of the same output, which applies the same layers. /theway:document, /theway:archive and /theway:list read no other key.

A config.yaml written by an earlier install may still have changes: and templates: sections, and file and description keys: each one gives an unknown key warning from theway config. It may also have interaction and develop entries under standards:: those standards cannot be switched, and each entry gives a cannot be switched warning. An engineering: section gives unknown key engineering, and so does a workflow: section: theway no longer reads workflow.defaults, so set a value in the workflow file or in the prompt's header instead. tamm_framework, spec_review and spec_investigation entries under standards: give a has no standard file warning: those files are prompts now. You can delete them all.

LayeringCopy Anchor Link

theway config builds the effective config key by key: the defaults below, then the global config.yaml, then the project's config.yaml. For each key it takes the project file's value when it is present and valid, else the global file's value when it is present and valid, else the default. A section the project file leaves out keeps the global values, and so does every key it leaves out of a section it sets.

An invalid value is ignored with a warning on stderr, so the layer below applies: an invalid project value falls back to the global value, and an invalid global value to the default. Each warning names the file relative to the home:

theway: warning: <file>: <key> must be <rule>; ignored
theway: warning: <file>: unknown key <key>; ignored
theway: warning: <file>: <key> must be a map; ignored
theway: warning: <file>: not a map; ignored
theway: warning: <file>: standards.<key> has no standard file; ignored
theway: warning: <file>: standards.<key> cannot be switched; ignored

<rule> is true or false. An unknown key is reported once, at its highest unknown level: an unknown section changes: gives unknown key changes, not one warning per entry. A section that is not a map contributes nothing below it, and a file whose root is not a map contributes nothing. An empty or comment-only file contributes nothing, without a warning. The global file's warnings come first, then the project file's, each in file order. Invalid YAML is an error, not a warning: see theway config.

For example, with the shipped global config.yaml, this <home>/projects/-home-you-code-my-api/config.yaml of the project at /home/you/code/my-api:

standards:
  sre:
    enabled: true
  quality:
    enabled: yes

makes theway config, run in my-api, print this, with one warning on stderr, theway: warning: projects/-home-you-code-my-api/config.yaml: standards.quality.enabled must be true or false; ignored:

standards:
  core_principles:
    enabled: false
  sre:
    enabled: true
  web_development:
    enabled: false
  quality:
    enabled: false

standardsCopy Anchor Link

standards.<key>.enabled switches any standard: the four opt-in standards theway ships and your own user standards. The key is the file stem with - turned into _: web-development.md is standards.web_development, tdd.md is standards.tdd. Both the global and the project config.yaml take it, so a project can switch a global standard off, or an opt-in one on, for itself only (see Switching a standard).

• The four opt-in standards default to false. The commands that read standards, /theway:engineering, /theway:workflow and /theway:document, read one only when its enabled is true.
• User standards default to true.
• theway config prints the four opt-in keys first, in the order below, then the key of every user standard of the project, sorted, each with its effective enabled.
• A key with no standard file behind it, in either file, is ignored with a has no standard file warning.

The other shipped standards are always read and have no switch: interaction.md by /theway:workflow (and so /theway:engineering), /theway:document and /theway:archive; develop.md by /theway:workflow, inline or through its implementer agent; authority.md through theway authority: /theway:workflow, /theway:document and /theway:archive follow the text it prints, and every agent /theway:workflow spawns gets it. Their keys, interaction, develop and authority, give a cannot be switched warning, unless the project holds a file with that name in <home>/projects/<key>/standards/: that file is a user standard with its own switch. A global authority.md that .shipped.json does not list is your own: a user standard with the key authority, switched like any other, and theway authority prints the shipped authority.default.md instead. commits.md and git-host.md, the convention standards /theway:workflow follows, have no switch either: standards.commits and standards.git_host always give a cannot be switched warning, and a project file with either name overrides the global one instead of being a user standard.

A config.yaml written by an earlier install has standards.architecture instead of these four entries. standards.architecture gives a has no standard file warning from theway config, and the four stay off until you copy them from config.default.yaml and set enabled: true on the ones you want.

User standards, your own files in <home>/standards/ and <home>/projects/<key>/standards/, need no config entry: they are on until a standards.<key>.enabled: false switches them off.