Standards

A user standard is a Markdown file of your own rules, such as test-first, that /theway:engineering, /theway:workflow and /theway:document follow on top of theway's shipped standards. You write it once, outside any repository, and it survives every install.

The two foldersCopy Anchor Link

~/.theway/
├── standards/          every project
│   └── tdd.md
└── projects/
    └── <key>/          one project, keyed by its path
        ├── changes/
        └── standards/  this project only
            ├── tdd.md  replaces the global tdd.md for this project
            └── review.md

• <home>/standards/ holds the standards of every project.
• <home>/projects/<key>/standards/ holds the standards of one project, beside its changes/ folder. <key> is the project key that theway project prints.

Both folders are optional. Install never touches your files in them.

<home>/standards/ also holds the standards theway ships. Their names decide what they are, whatever .shipped.json says:

• interaction.md, develop.md and authority.md are always read by the commands that need them, never listed and never switchable; a global authority.md that .shipped.json does not list is your own standard instead, listed and switched like any other, and theway authority then prints the shipped authority.default.md.
• The engineering procedures are not standards: the TAMM framework, the investigation rules, the critics' rules and lenses, the verdicts and the spec templates are prompts of the engineering workflows (prompts/tamm-framework.md, prompts/spec-investigation.md, prompts/spec-review.md, …). Install retires the old standards/ copies: an unedited one is removed, an edited one is renamed to .bak, so that it never becomes a standard every agent gets.
• commits.md and git-host.md are the convention standards: /theway:workflow reads them by path, they are never listed, from either folder, and never switchable.
• core-principles.md, sre.md, web-development.md and quality.md are the opt-in standards: off by default and, when switched on, read by every command that reads standards, like yours. A file of yours kept at one of these names counts as that opt-in standard.
• Any other name .shipped.json lists as standards/<name>, and any *.default.md copy, is theway's, never a user standard.

When theway starts shipping a name you already use there, install keeps your file and warns (see What install writes).

Order: the global files come first, opt-in and user standards together, then the project files, each group sorted by name.

Same name: when both folders hold a file with the same name, the project file replaces the global one, user or opt-in, for that project, but only for the phases the project file applies to. For the other phases, the global file is listed as usual when it applies and is switched on. For example, a project sre.md with applies_to: [develop] replaces the global sre.md for develop, and engineering and document still list the global one. The project file is a user standard, but it keeps the key of its name, so the switches of both config files apply to both files: with the shipped config.yaml, which sets standards.sre.enabled: false, a project sre.md stays off until the project's config.yaml sets standards.sre.enabled: true. A project file named like an always-read standard, such as develop.md, is a user standard too: on by default, listed by theway config and switched by standards.develop.enabled; the commands still read the shipped develop.md.

The conventionCopy Anchor Link

Every other .md file directly in either folder is a user standard. No config key declares it, and it is on until you switch it off (see Switching a standard). Subfolders and other files are ignored.

For example, <home>/standards/tdd.md:

# Test first

Write the failing test before the code that makes it pass.

Without frontmatter, it applies to /theway:engineering, /theway:workflow and /theway:document.

applies_toCopy Anchor Link

An optional applies_to in the file's frontmatter limits a standard, yours or a shipped opt-in one, to some phases. The values are engineering (/theway:engineering, with or without --light), develop (/theway:workflow) and document (/theway:document). It takes a flow list or a block list:

---
applies_to: [develop]
---

---
applies_to:
  - engineering
  - develop
---

• A file without frontmatter, or whose frontmatter has no applies_to: line, applies to all three phases.
• Any other value or form is invalid: an enabled file applies to no phase, and theway standards warns on stderr:

theway: warning: <path>: applies_to must list engineering, develop and/or document; skipped

The command quotes that warning in its report, so you can fix the file. The same rule holds for the opt-in standards: the shipped files have no frontmatter, so they apply to all three phases, and adding an applies_to to one narrows it.

Switching a standardCopy Anchor Link

standards.<key>.enabled in config.yaml switches any standard, the opt-in ones and yours. The key is the file stem with - turned into _: tdd.md is standards.tdd, code-review.md is standards.code_review. Two files whose stems give the same key, such as a-b.md and a_b.md, share it. When one of them is a shipped opt-in standard, such as web-development.md beside your web_development.md, the key defaults to false.

• Defaults: the four shipped opt-in standards are off, user standards are on.
• Project override: the project's <home>/projects/<key>/config.yaml overrides the global one key by key (see Layering), so a project can switch a global standard off, or an opt-in one on, for itself only.
• A switched-off standard is not listed by theway standards, so no command reads it.
• A key with no standard file behind it is ignored with a warning, so a misspelled key does not pass silently:

theway: warning: <file>: standards.<key> has no standard file; ignored

theway config prints every switchable standard of the project with its effective value.

For example, to keep a global <home>/standards/tdd.md for every project but my-api (at /home/you/code/my-api), write <home>/projects/-home-you-code-my-api/config.yaml:

standards:
  tdd:
    enabled: false

Run in my-api, theway config then prints tdd with enabled: false, and theway standards engineering no longer lists tdd.md. Every other project still reads it.

Convention standardsCopy Anchor Link

Two shipped standards hold the team conventions and the git host commands that the shipped prompts of /theway:workflow follow, so that neither the command nor its pipeline fixes them:

• commits.md: the feature branch name (<change-id>), the commit type from the change ID's verb (add- → feat, fix- → fix, refactor- → refactor), Conventional Commit messages, and the PR title and body.
• git-host.md: one ## heading per git host operation (Default branch, Sync the default branch, Push the feature branch, Open the PR, Wait for the checks, Read a failed check's log, Re-run failed jobs, Diffstat, Merge), each with its command; the shipped file uses GitHub through the gh CLI. The command and the prompts name an operation by its heading, never a command.

They differ from the other standards:

• Read by path: the prompts read standards/commits.md and standards/git-host.md by path (prompts/change.md), your project's copy first, as every agent's file path rule says. They are never in theway context's standards.
• Editable: edit <home>/standards/commits.md or git-host.md; install keeps your edited file and writes the shipped one next to it as commits.default.md or git-host.default.md.
• Project override: <home>/projects/<key>/standards/commits.md or git-host.md replaces the global file for that project. A project file with one of these names that was one of your standards becomes that override.
• Not switchable: standards.commits and standards.git_host give a cannot be switched warning.

For example, a project on GitLab replaces git-host.md with <home>/projects/<key>/standards/git-host.md, which keeps the nine headings and gives the glab command under each, such as:

## Open the PR

`glab mr create --source-branch <branch> --target-branch <base> --title <title> --description <body>`.

## Merge

`glab mr merge <number> --squash`. Never bypass required reviews or checks.

Who reads themCopy Anchor Link

The commands get them from the standards list of theway context <engineering|develop|document>, the paths theway standards prints for that phase, and read every file it lists: for each phase, the enabled standards, shipped opt-in or yours, that apply to it; each applies to every phase unless its applies_to narrows it. When the installed theway is too old to know context, the command tells you to run npx --yes @pixelfactoryio/theway@latest install then /reload-plugins, and stops; when theway context exits 1 for another reason, it quotes the error and stops. Standards are binding, not guidance:

• /theway:engineering, with or without --light, writes the spec and tasks with them, the enabled opt-in standards included. A request that contradicts one is an open question without --light, and an escalation with it. The critics get their paths: the implementability critic (the grounding critic with --light) reports a spec or task that contradicts one.
• /theway:workflow follows them, in your session for an inline work agent and through its agents otherwise. When one contradicts the spec, the implementation stops and brings it back.
• In /theway:workflow, the reviewers check the diff against them: a violation is a finding that names the standard file and the rule it breaks. The fix agents get them too, and the fix check marks a finding not resolved when its fix breaks one. Every agent of the run gets their paths; the implementer, the reviewers and the fix check are the ones asked to apply them.

Every report of these commands names the standards used, by file name, or "none". /theway:document follows the standards that apply to document when it writes the docs.