Skip to content

12 AI Agents

RemyDuijkeren edited this page Nov 8, 2026 · 7 revisions

AI Agents

AI agents and CI scripts can drive Flowline through its exit codes and error messages, which name the corrective action. There's also an agent plugin for Claude Code and Codex.

Claude Code / Codex plugin

Install the plugin so Claude Code or Codex knows how to drive Flowline:

# Claude Code
/plugin marketplace add RemyDuijkeren/Flowline
/plugin install flowline@flowline

# Codex
codex plugin marketplace add RemyDuijkeren/Flowline
codex plugin add flowline@flowline

It ships five skills, and the agent loads the relevant one on its own.

  • flowline: the core loop, push --dry-run → push → pull → deploy, and branching on exit codes.
  • flowline-plugins: plugin steps and Custom APIs, class naming and attributes. See Push Plugins and Custom APIs.
  • flowline-webresources: web resource naming, form event handlers and // flowline: annotations. See Push WebResources.
  • flowline-generate: early-bound types and the generators. See Generate Early-Bound Types.
  • flowline-migration: detects a spkl, Daxif, PACX, or ALM Accelerator project and walks through the matching guide (spkl, Daxif, ALM Accelerator, PACX), then checks the result with push --dry-run and pull.

Exit codes

Exit codes are stable across versions.

Codes 3, 4, and 130 follow de facto CLI conventions (curl, git, rsync). Codes 10 to 21 are Flowline-specific.

Code Name Meaning Corrective action
0 Success Command completed None
1 GeneralError Unexpected/unhandled error Check error output
3 NotFound Solution not in Dataverse or repo Verify solution name matches .flowline
4 NotAuthenticated No PAC auth profile Run: pac auth create --environment <url>
10 ConnectionFailed Dataverse environment unreachable Check environment URL in .flowline
11 ConfigInvalid .flowline or a settings file is missing or malformed, or a role keyword was used with no project to resolve it from Verify the named file exists and is valid. For a role keyword outside a project, pass the environment URL instead
12 DirtyWorkingDirectory Uncommitted git changes block the operation git commit or git stash first
13 BuildFailed dotnet build or PAC pack failed Fix errors in Plugins/ and retry
14 VersionConflict Reserved: allocated in the exit-code contract but never thrown today None; this code doesn't currently occur
15 ValidationFailed Drift detected, missing dependencies, invalid --force value, schema mismatch, flags that contradict each other, a target that is neither a role nor a URL, a role whose .flowline value isn't a URL, an environment whose type doesn't fit its role (such as deploy prod aimed at a sandbox), a scripted settings toggle/set write with no component name, or a managed deploy target still holding a staged upgrade Run flowline pull first; check error output. A staged upgrade prints the pac commands that clear it. An invalid --force value lists the ones that are valid for that command, and a flag conflict names both flags
16 Timeout A Dataverse request got no response, or the PAC CLI 60-minute limit was exceeded Re-run the same command. The write may already have landed, and the reconciling commands converge on a re-run; check environment health if it repeats
17 ForceRequired Destructive or overwriting operation requires explicit confirmation: a declined confirmation (e.g. deploy's first-import prompt), provision refusing to overwrite an existing target, or a .flowline config overwrite declined non-interactively Add the --force <specifier> the message names, e.g. --force first-import, --force overwrite, --force config, --force recreate-assembly
18 PartialSuccess The run finished but part of it failed: deploy's orphan cleanup couldn't remove some components, settings apply couldn't write some of them, or a settings capture sweep couldn't reach an environment One failure and every failure share this code; read the printed counts. Fix what the output names, then re-run — both commands are safe to repeat
19 Inconclusive A check couldn't run to completion: drift's empty-input guard skipped the comparison, a deploy verification step couldn't finish (e.g. a locked directory or a Dataverse query fault), or every component a settings apply file declared was absent from the target Not a pass/fail signal. Investigate the printed reason before trusting the result. For settings apply it usually means the wrong settings file or the wrong environment
20 WriteTargetOccupied A file already occupies a path the command would write to: scaffold meeting an existing template file, or --output pointing at a file rather than a folder Distinct from 11: nothing is missing or malformed, something valid is in the way. Move the named file aside, or run the command somewhere else
21 AssemblyNotRegistered Deploy completed but a plug-in package holds an assembly with no registration in the target, or one registered with no plugin types Create the pluginassembly record under that package (sandbox isolation, matching version/culture/public key token), then deploy again so the content write populates its plugin types. This repeats every deploy until that record exists
22 ChangesFound diff --exit-code or drift --exit-code found changes between the two compared points Not a failure: the comparison ran and something differs. Only returned when --exit-code is passed, so a run without it reports changes and still exits 0
130 Cancelled Ctrl+C / SIGINT, the only way to reach this code. A second Ctrl+C quits without waiting for the run to unwind Re-run if needed

Codes 2 and 5 are intentionally unused.

Error messages

Every error message says what happened and what to do next. These include the fix verbatim:

Code Message includes
4 (NotAuthenticated) run: pac auth create --environment <url>
12 (DirtyWorkingDirectory) Commit or stash changes first
17 (ForceRequired) Use --force <specifier> to proceed, and the specifier named is always valid for the command that raised it

Command selection

Command What it does When to run What changes after
clone Initialize project from an existing Dataverse solution One-time setup per solution that already exists Folder structure, unpacked XML, Plugins and WebResources projects, AGENTS.md, CLAUDE.md, DATAVERSE_CONTEXT.md
init Create publisher + empty unmanaged solution in DEV, then scaffold One-time setup when the solution does not exist in Dataverse yet Publisher and solution created in DEV; then everything clone produces; DEV URL saved to .flowline
push Register plugins and web resources to DEV After plugin or web resource changes DEV reflects current source; no pack/import involved
pull Export from DEV, bump version, unpack to XML After testing changes in DEV Solution/src/ updated; build version bumped; DATAVERSE_CONTEXT.md regenerated
deploy Pack and import into target environment After pull + commit Target environment updated with current solution version
provision Create environment by copying from PROD One-time setup for new environments Environment URL saved to .flowline
generate Generate early-bound C# types from solution After adding or modifying entities or custom APIs Plugins/Models/ overwritten with generated .cs files
settings apply <target> Apply a settings file: environment variable values, connection reference bindings, component state After deploy Only the components the file names change; re-running the same file changes nothing. --dry-run writes nothing
settings capture <target> Write a settings file from an environment To create the file, or refresh it Name the environment: omitting it exits 15 in a non-interactive run, and only prompts for which to capture at a terminal. Merges rather than overwrites. Secrets are never read; a placeholder is written instead
settings toggle <target> [name] Turn one component on or off, or read its state To toggle a component without a redeploy or a file edit Give --on or --off to write, neither to read. --type flow|workflow|rule|bpf|action|plugin narrows it. Omit the name of a write in a non-interactive run and it exits 15, printing your command with <name> to fill in. Omit it on a read and it lists the components and exits 0, one per line as <glyph> <state> <type> <name> (● on, ◐ suspended, ○ off), ordered suspended then off then on. Forms and views are left out unless --type form or --type view is given; a full name still resolves them
settings set <target> [name] Set one value or binding, or read it To change one value without a redeploy or a file edit Give --value to write, omit it to read. --type envvar|connref narrows it. An empty value is refused. Omit the name of a write in a non-interactive run and it exits 15, printing your command with <name> and <value> to fill in. Omit it on a read and it lists the names, without their values, and exits 0
drift Report what deploy's orphan cleanup would delete Before deploy, or as a standalone check on prod/test Read-only, nothing changes
diff Report which solution components changed between two points in git history Before a commit, or between two tags to read what a release contains Read-only, nothing changes unless --write is passed
scaffold Write a project template (webresources) into the current folder Adding web resources to a repo that has none WebResources/ project written where you are standing, and added to the nearest solution file (searched upward to the .flowline/.git root) when there is one. --output moves the folder, --name names it. No Dataverse call
status Show environment, auth, and git state Before running commands; when troubleshooting Read-only, nothing changes
sln add Add a .cdsproj to the solution file A repo assembled by hand or migrated off another tool Solution file updated, found by searching upward to the .flowline/.git root, same rule as scaffold. No Dataverse call

Daily dev loop

dotnet build                       # build plugin assembly
flowline push                      # register DLL + web resources in DEV
flowline push --dry-run            # preview changes before touching Dataverse
# make changes in the maker portal if needed
flowline pull                      # pull solution state from DEV, unpack to repo
git add . && git commit -m "..."   # commit the unpacked XML diff
flowline deploy test               # promote to TEST
flowline deploy prod               # promote to PROD

Rules

  • Use Flowline, not pac solution directly.
  • Pick init vs clone by whether the solution already exists in Dataverse. init creates one and refuses a unique name that's already taken; clone adopts an existing one.
  • init runs against Sandbox and Developer environments only. Anything else is refused with exit 15.
  • init never prompts in a non-interactive run. Pass <solution-name>, --env <url>, and --publisher-prefix <prefix>. Each missing one fails naming the flag.
  • -e/--env <role|url> targets clone, init, push, pull, and generate. init, push, and pull accept DEV only: the dev keyword, the saved DEV URL, or a URL Flowline reads as DEV (not Production, and not named -test/-uat); passing anything else fails naming that. generate accepts any role; clone accepts any role too, since it's usually reading from PROD. A URL not yet in .flowline gets saved under the role Flowline infers from it, or the one you pick interactively.
  • pull requires a clean working directory. Exits 12 if there are uncommitted changes in Solution/src/. Commit or stash first.
  • deploy packs from source, not from a previous export. Local changes not yet synced to DEV exit 15. Run pull first.
  • --force <specifier> is required for destructive operations in non-interactive mode. --force always takes a value naming the exact hazard being approved (e.g. --force dirty, --force config, --force overwrite). Without it, Flowline exits 17. See 04-Command-Reference for the per-command --force vocabulary.
  • status is read-only. Use it to check connectivity and auth.
  • Unknown flags fail strictly. An option Flowline doesn't recognize, including an old or removed spelling, fails with Error: Unknown option '<name>'. and exit 15.

Project structure

.flowline                              ← environment URLs + solution config
docs/DATAVERSE_CONTEXT.md              ← schema snapshot for AI agents (auto-generated)
Solution/<SolutionName>.cdsproj        ← solution metadata
Solution/src/                          ← unpacked solution XML (git-diffable)
Plugins/<SolutionName>.Plugins.csproj  ← plugin source, decorated with [Step] attributes
WebResources/<SolutionName>.WebResources.csproj  ← web resource build project
WebResources/dist/                     ← web resource files synced to Dataverse by push
AGENTS.md                              ← scaffolded by flowline clone / init (this file)
CLAUDE.md                              ← scaffolded by flowline clone / init (`@AGENTS.md` import)

Need a genuine second solution in one repo? Two documented patterns: a separate repo per solution (default), or a nested solutions/<Name>/ folder inside one repo containing multiple independent, self-contained Flowline projects (each with its own .flowline, Solution/, Plugins/, WebResources/).

AGENTS.md scaffolding

flowline clone writes an AGENTS.md file at the repo root with the solution name substituted throughout. It includes:

  • The daily dev loop for this specific solution
  • Project structure with actual paths
  • Exit code reference table
  • Rules for this project

An existing AGENTS.md is never overwritten.

GitHub Copilot and Codex load AGENTS.md automatically on project open. Claude Code does not read AGENTS.md directly, it only auto-loads CLAUDE.md, so flowline clone also scaffolds a one-line CLAUDE.md containing @AGENTS.md, which Claude Code resolves as an import. Same skip-if-exists behavior applies. Keep AGENTS.md accurate as the project evolves.

Dataverse schema context

After every successful flowline clone or flowline pull, Flowline writes docs/DATAVERSE_CONTEXT.md, a curated markdown snapshot of the solution schema optimised for AI token efficiency.

What it contains

Section Content
Solution Display name, unique name, version, publisher prefix
Entities Logical name, display name, EntitySetName, ownership type
Attributes Logical name, type, required level, description, custom flag
Option sets Inline value → label mapping for picklist and boolean fields
Forms Condensed tab → section → field list (hidden controls excluded)
Views Column list and filter summary (no verbatim FetchXML)
Workflows Display name, activation state, trigger entity
Plugin steps Message, entity, stage (pre/post-operation), mode (sync/async), class name
Connection references Display name, connector ID

Sections with no content are omitted. No GUIDs appear in the output.

AGENTS.md integration

flowline clone seeds AGENTS.md with a "Dataverse schema context" section at the end:

## Dataverse schema context
- [ContosoSales](docs/DATAVERSE_CONTEXT.md)

@docs/DATAVERSE_CONTEXT.md

The @ import causes Codex and GitHub Copilot to load the schema automatically on every request from AGENTS.md, and Claude Code to load it via the CLAUDE.md → AGENTS.md import chain.

Every flowline pull adds the import and link back if they're missing. Without an AGENTS.md, pull warns; run flowline clone to scaffold it.

Clone this wiki locally