Vale integration

Overview

Vale is an open-source prose linter that enforces style rules across documentation. When Vale is configured for a doc collection, Promptless lints the prose it writes 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 can also propose Vale rules from your style guidance.

This guide covers creating a Vale config, connecting it to a doc collection, and choosing how strictly Promptless fixes findings.

Before you start

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

Create a Vale config

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.

Connect Vale to a doc collection

Promptless turns on Vale linting automatically when it detects a Vale configuration file in your docs repository. To use a different config file, set the path yourself.

Automatic detection

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, Vale linting activates 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.

Set the config path manually

On the Doc collections tab of the Configuration page, expand the doc collection.
Select More filters (optional).
In Vale config path, enter the repo-relative path to your Vale configuration file, such as .vale.ini or docs/.vale.ini.
Select Save changes.

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

How Promptless runs Vale

After drafting prose content, Promptless:

Syncs packages. Downloads the external style packages your config references, such as Microsoft, Google, or write-good, when they aren’t already vendored in your repository. Promptless downloads them the first time it lints during a session.
Lints prose. Runs Vale on every prose file it creates or substantially edits.
Applies your alert level. Reads your config’s MinAlertLevel and uses it to decide which findings to fix. See Severity handling.
Matches your CI. Reads the Vale job in your repository’s GitHub Actions workflows and reproduces that invocation on the changed files. The run confirms the files pass before Promptless creates the suggestion.

Vale runs only on prose content. Code blocks, commands, configuration, frontmatter, schemas, and tables are excluded from linting.

Vale errors can still slip through or arise from later edits. When Vale fails in a GitHub Actions workflow on a Promptless PR, Promptless analyzes the failure and pushes fixes to the branch. The same handling covers other CI checks, such as broken-link detection and Doc Detective tests.

Severity handling

Vale classifies violations into three severity levels:

Severity	Behavior
error	Blocking. Promptless fixes these before creating the suggestion.
warning	Advisory. Promptless evaluates against your existing style and fixes when appropriate.
suggestion	Advisory. Promptless considers these but may preserve intentional style choices.

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

When MinAlertLevel is set

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. To have Promptless fix fewer findings, raise the level, for example to warning or error.

When MinAlertLevel is unset

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.

Propose Vale rules from your style guidance

During doc collection analysis, Promptless reads your collection’s style guidance and proposes Vale rules that capture it. This runs on its own, without a request from you. Promptless analyzes your collection when you connect a docs repository and each time it re-analyzes the collection. The rules go two places:

Promptless records them under a style/vale/ area in your Agent Knowledge Base.
When Promptless can place the rules in your documentation repository, it proposes them as a suggestion. The suggestion carries a branch and a pull or merge request, and you review it before anything merges.

Enforcement lints your prose against the Vale rules you already have. This capability writes the rules themselves from your style guidance.

Supplement or bootstrap your Vale setup

When your collection already has a Vale configuration, Promptless supplements it with the proposed rules. When your collection has no Vale configuration, Promptless can bootstrap one so the rules have a place to run. A bootstrapped config arrives inside the same suggestion, so nothing lands in your repository without your review.

How guidance maps to severity

Promptless sets each proposed rule’s severity from how firmly your collection states the guidance:

Guidance your style guide states becomes an enforced rule at error or warning severity.
A strong convention observed across your docs becomes an advisory rule at suggestion severity.

For how Promptless acts on each severity once the rules run, see Severity handling.

You decide what gets enforced

You review the proposed rules in the suggestion and decide whether to promote an advisory suggestion rule to an enforced error or warning rule. Promptless doesn’t promote a rule on its own.