Skip to content

For the complete documentation index, see llms.txt.

Vale integration

Vale is an open-source prose linter that enforces style rules across documentation. Promptless lints the prose it writes with Vale and fixes style violations before they reach your review queue. Suggestions then match your style guide from the start, with less back-and-forth during review. Promptless also writes Vale rules from your style guidance and keeps them current.

Promptless runs Vale with its default rules even when your repository has no Vale config. This guide covers how to add your own Vale config to that run and how to choose which findings Promptless fixes.

  • An admin role in your Promptless organization, to set the Vale config path on the Configuration page.

If you don’t have a Vale configuration yet, create a .vale.ini file in your docs repository root:

StylesPath = .vale/styles
MinAlertLevel = warning
[*.md]
BasedOnStyles = Vale

This minimal config enables Vale’s built-in rules. For more comprehensive style enforcement, add external packages:

StylesPath = .vale/styles
MinAlertLevel = warning
Packages = Microsoft, write-good
[*.md]
BasedOnStyles = Vale, Microsoft, write-good

See the Vale documentation for detailed configuration options and available style packages.

Promptless lints with your Vale config when it finds a Vale configuration file in your docs repository. To use a different config file, set the path yourself.

During doc collection setup, Promptless scans the collection for a Vale configuration file matching any of the five names Vale recognizes: .vale, _vale, vale.ini, .vale.ini, or _vale.ini. When Promptless finds one, it lints the collection with that config. When the scan finds more than one candidate, Promptless uses the config in the shallowest directory within the collection’s scope. It breaks ties by the filename order above.

  1. On the Doc collections tab of the Configuration page, expand the doc collection.

  2. Select More filters (optional).

  3. In Vale config path, enter the repo-relative path to your Vale configuration file, such as .vale.ini or docs/.vale.ini.

  4. Select Save changes.

In YAML mode, set the same path as the collection’s vale_config_path.

Before it creates a suggestion, Promptless runs Vale on each prose file that it created or substantially edited, and fixes the findings. It does this for every doc collection, with or without a Vale config.

Promptless lints with these rules:

RulesWhen Promptless uses them
Promptless default rulesAlways. The list is below this table.
Your organization’s rule setWhen the rule set exists. Promptless writes it from your style guidance, or syncs it from your rules repository. See Vale rules.
The doc collection’s Vale configWhen the collection has a Vale config. See Connect Vale to a doc collection.

Your Vale config takes precedence. A rule that your config turns off, or sets a level for, keeps that setting.

Promptless default rules
RuleLevelWhat it flags
House.ScaffoldingerrorSentences about the document itself, not its subject.
Voices.BannederrorInflated words that need the sentence rewritten.
Voices.BinaryContrasterrorA sentence that negates one idea to set up a grander one.
Voices.ColonRevealwarningA short phrase, a colon, then a reveal.
Voices.InflatedWordserrorInflated words that have a plain replacement.
Voices.PufferyerrorClaims that something is important or impressive.
Voices.RecaperrorEndings that restate what the text already said.
Voices.SuperficialAnalysiserrorTrailing “-ing” clauses that add an unsupported claim.
Voices.ThroatClearingerrorOpeners that announce a point before they make it.
Voices.WeakVerbserrorVerb phrases that one verb can replace.
Voices.WeaselerrorAppeals to unnamed sources.
Direct.HedgingerrorQualifiers that soften a claim.
Direct.LengtherrorSentences over 25 words.
Direct.PreambleerrorLead-ins that delay the point.
Moose.EmDasherrorEm dashes and double hyphens.

To turn off a default rule for a doc collection, set it to NO in the collection’s Vale config, for example Direct.Length = NO.

When a doc collection has its own Vale config, Promptless also runs the same Vale command as your CI:

  1. It reads the Vale job in your GitHub Actions workflows or .gitlab-ci.yml. If the job calls a wrapper script, it reads the script too.
  2. It downloads the style packages that your config references, such as Microsoft or write-good, if they aren’t in your repository.
  3. It runs the command on the files it changed.

Vale lints prose only. It skips code blocks, commands, configuration, frontmatter, schemas, and tables.

To add a check that Promptless must run, write the command in PROMPTLESS.md in your Agent Knowledge Base. State that the command must pass. Promptless then pushes the branch only after the command passes.

If Vale fails in CI on a Promptless suggestion, see CI check and build fixes for GitHub or Pipeline failures for GitLab.

Vale classifies violations into three severity levels:

SeverityBehavior
errorBlocking. Promptless fixes these before creating the suggestion.
warningAdvisory. Promptless evaluates against your existing style and fixes when appropriate.
suggestionAdvisory. Promptless considers these but may preserve intentional style choices.

How Promptless treats findings depends on whether your config sets MinAlertLevel.

Setting MinAlertLevel sets the severity bar your docs hold to. Promptless fixes every finding Vale reports at or above that level, including warnings and suggestions. That mirrors what your Vale CI reports, so Promptless resolves findings you’d otherwise see as review comments before the suggestion reaches you.

For example, with MinAlertLevel = suggestion, Promptless fixes every error, warning, and suggestion Vale reports. Use this level when your CI fails on any Vale alert. To have Promptless fix fewer findings, raise the level, for example to warning or error.

When your config doesn’t set MinAlertLevel, Promptless treats error-severity rules as hard constraints. It treats warning and suggestion rules as guidance and balances them against the established voice and conventions in your docs.