> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/sfp/analysing-a-project/ai-version-assist.md).

# AI Assisted Version Intent

{% hint style="warning" %}
**This feature is in limited preview** — it is available to selected customers only, and behaviour and commands may change based on feedback. Reach out to the flxbl team if you would like early access.
{% endhint %}

{% hint style="info" %}
AI Version Assist is part of [Automated Package Versioning](/flxbl/sfp/building-artifacts/automated-package-versioning.md). It requires an sfp server with version management enabled, and an AI provider configured for the project.
{% endhint %}

[Automated package versioning](/flxbl/sfp/building-artifacts/automated-package-versioning.md) computes each artifact's version from the last published version and the **intent** of the change. Intent normally comes from a human — a conventional commit prefix, a `version:` footer, or a `/version` pull request comment. When none is given, the change falls through to a patch.

AI Version Assist adds a machine author for that intent. It runs as an addon inside `sfp project:analyze`, reads what the pull request diff actually does, and posts a single `/version` comment on the PR authored by the app. The build reads that comment through the same collector as a human `/version` comment — as a distinct, lower-priority tier. A human `/version` comment always overrides it.

### How it works

The assist rides the existing pull request analysis flow — it does not introduce a separate trigger. On a PR event (opened, synchronize, reopened, ready-for-review), `project:analyze` runs its linters, and the version-assist addon runs last:

1. Maps the PR's changed files to packages, using the same mapping the version pipeline uses.
2. Keeps only the **server-managed** packages — those carrying `0.0.0.NEXT` in `sfdx-project.json`.
3. Scores each impacted package from its own diff (`major`, `minor`, `patch` or `none`).
4. Posts — or edits — one sticky `/version` comment on the PR carrying the resulting directive and a rationale table.

```
PR opened / synchronize ─▶ project:analyze ─▶ version-assist addon
                                                    │
                        sticky /version comment ────┘
                                                    ▼
                     build reads it as the AI tier ─▶ source: ai
                     (a human /version always wins)
```

The assist is a participant in the existing primitive, not a new mechanism. Its output is a `/version` comment; the build's version pipeline is unchanged.

### When it runs — three gates

All three conditions must hold, or the addon is silently skipped:

1. **Version management is enabled** for the project (`versionManagement.enabled`). This is the same project-level gate that automated package versioning uses.
2. **The addon is enabled** for the target branch (`analyzeConfig.versionAssistEnabled`). This defaults to **off** and is set per project, optionally per branch.
3. **The PR impacts at least one server-managed package** (a `0.0.0.NEXT` package). A PR that only touches manually versioned packages is skipped.

### The sticky comment

The assist maintains exactly **one** comment per pull request. Re-running the analysis after new commits edits that comment in place rather than posting a second one. The comment carries a `/version` directive line, a rationale table, and a hidden marker (`<!-- sfp-version-assist -->`) that identifies it as the assist's output.

```
/version core:minor sales-app:patch dependents:patch

### AI version assessment
| Package   | Suggested | Evidence                                    |
|-----------|-----------|---------------------------------------------|
| core      | minor     | adds AccountScoreService (new public class) |
| sales-app | patch     | internal refactor of OpportunityHandler     |

Override by posting a later /version comment — human comments always win.
<!-- sfp-version-assist -->
```

The `/version` line starts the comment so the build's collector reads the directive. Editing in place preserves the comment's original creation time on GitHub, so the assist never gains recency over a human comment.

### How the intent is decided

The assist scores each impacted package from its diff — the removed and added lines, not the commit message or PR title. A removed public member is a breaking change even when the same PR also adds files. Each package gets exactly one intent:

| Intent  | Evidence required                                                                                                                                                                       |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `major` | A breaking change: a removed or renamed public/global Apex member, a removed or type-changed field, a removed permission/page/flow/API, or a new required parameter on a public method. |
| `minor` | A backward-compatible capability addition: new objects, fields, Apex classes or methods, flows, or LWCs that extend the package surface without breaking anything existing.             |
| `patch` | A behaviour-preserving change: bug fixes, internal refactors, metadata tweaks. This is the default when the evidence is ambiguous.                                                      |
| `none`  | Provably non-shippable content only: documentation, tests, or scratch-org config, with no deployable metadata change.                                                                   |

When a change alters an interface that other packages depend on, the assist may add `dependents:patch` to nudge the direct dependents — and only ever `patch`. Stronger dependents intents are mentioned in the rationale for a human to apply.

### Precedence — humans always win

The build resolves each package's version intent in this order:

| Priority | Source                          | Attributed as         |
| -------- | ------------------------------- | --------------------- |
| 1        | Human `/version` PR comment     | `pr-comment`          |
| 2        | `version:` commit footer        | `explicit`            |
| 3        | **AI Version Assist directive** | `ai`                  |
| 4        | Conventional commit prefixes    | `conventional-commit` |
| 5        | Patch default                   | `default`             |

The assist sits below every human-authored intent and above the derived defaults. A `/version` comment posted by a person for a package always overrides the assist's directive for that package, regardless of order. Comments carrying the assist marker form a separate, lower tier that a human comment cannot be outranked by.

When an AI-decided version is published, the baseline record stores `lastVersionIntentSource: 'ai'`, so release audits show which bumps were machine-decided. The `Computed Versions` table printed during the build shows `ai` in its **Source** column.

For the full intent model that the assist feeds into, see [Expressing version intent](/flxbl/sfp/building-artifacts/automated-package-versioning/expressing-version-intent.md).

### On cascade pull requests

A cascade opens an ordinary pull request, so the assist runs on it like any other PR. It reads the whole cascaded diff and suggests a bump for the packages it touches — it does not distinguish a cascade from original work. That suggestion cannot produce a spurious version:

* If the cascaded content is already published on the source line, the receiving build skips the package — no version is computed for it — so the directive is never applied.
* If the package does build, because the receiving branch has its own change to it, the version floor recognises the cascaded intent as already spent and does not re-apply it. The package takes its own intent for its own change.

In both cases the assist's directive on the cascade PR is inert. See [Versioning across branches](/flxbl/sfp/building-artifacts/automated-package-versioning/versioning-across-branches.md) for the floor and skip behaviour.

### Configuration

The addon is configured on the project, under `analyzeConfig`. It is off by default and can be turned on per target branch using the same first-match-wins branch rules as the other analyze settings:

```jsonc
"configuration": {
  "versionManagement": { "enabled": true },   // required — the project-level gate
  "analyzeConfig": {
    "versionAssistEnabled": false,             // addon default: off
    "branchRules": [
      { "pattern": "main", "versionAssistEnabled": true }
    ]
  }
}
```

{% hint style="info" %}
`versionAssistEnabled` is a project (server) setting resolved from `analyzeConfig`, not a field in the local `config/analyze.yaml`. The server keeps the per-branch resolution in one place.
{% endhint %}

The AI provider resolves exactly as it does for the [architecture linter](/flxbl/sfp/analysing-a-project/ai-pr-linter.md): the project's `aiProvider` setting, then the project's AI integration credentials, then the default AI integration. Setting `aiProvider: 'none'` opts the project out. See [Configuring LLM Providers](/flxbl/sfp/getting-started/configuring-llm-providers.md) for provider setup.

### Running it manually

The same analysis is available as a standalone command, useful for testing on a branch before enabling the addon:

```bash
sfp project version suggest \
  --repository flxbl-io/sf-core \
  --pr-number 42 \
  --base-ref origin/main
```

This prints the suggested directive and the per-package rationale without changing anything. Add `--apply` to post or edit the sticky comment on the PR:

```bash
sfp project version suggest \
  --repository flxbl-io/sf-core \
  --pr-number 42 \
  --base-ref origin/main \
  --apply
```

| Flag              | Description                                                                            |
| ----------------- | -------------------------------------------------------------------------------------- |
| `--repository`    | Repository identifier (required).                                                      |
| `--pr-number`     | Pull request number. Required to `--apply` the sticky comment.                         |
| `--base-ref`      | Base commit or branch for the diff (for example `origin/main`).                        |
| `--head-ref`      | Head commit or branch for the diff. Defaults to `HEAD`.                                |
| `--changed-files` | Comma-separated list of changed files, overriding the git diff.                        |
| `--provider`      | AI provider override (for example `anthropic`). Defaults to the project's integration. |
| `--apply`         | Post or edit the sticky `/version` comment on the PR. Off by default.                  |
| `--json`          | Emit the result as JSON instead of a table.                                            |

### Failure posture

The addon is advisory only. A missing provider, exhausted quota, timeout, or model error causes the analyzer to report the version-assist check as skipped and post no directive. It never fails the analysis check and never blocks a build.

### Where the results appear

The assist delivers its result through three channels:

* The **sticky `/version` comment** on the pull request — the directive the build reads.
* An informational **check run** (`sfp Project Analysis - version-assist`), alongside the other analyze checks.
* The **analysis record** surfaced in the codev Change Analysis area, where the assessment appears as its own tab.

### Provider support

GitHub is supported first. Azure DevOps support is planned for a later phase — comment timestamps, which the sticky-comment behaviour relies on, are not always available there.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.flxbl.io/flxbl/sfp/analysing-a-project/ai-version-assist.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.