---
name: workflow-code-operations
description: Use when initializing, configuring, compiling, syncing, publishing, or troubleshooting source-first Tela Workflow Code projects through the tela workflow CLI, including config, targets, env files, Tela Local contexts, lockfiles, environments, and diagnostics.
---

# Workflow Code Operations

Operate Workflow Code projects only through the routed `tela workflow` CLI. Use
`workflow-code-builder` for authoring source declarations and use the direct Tela API workflow path
only when the user explicitly requests it.

## Load the Installed Documentation

Treat the version-matched documentation bundled with the installed CLI as the source of truth for
commands, flags, config, modules, lifecycle behavior, and diagnostics. Do not reconstruct those
details from this skill or memory.

Before planning or running a Workflow Code operation:

1. Run `tela --version`.
2. Run `tela workflow docs --json` and record its `packageName`, `packageVersion`, `sourcePackage`,
   and available pages. Require `sourcePackage` to identify `@meistrari/workflow-code-page`.
3. Read only the pages relevant to the task with `tela workflow docs <page> --json`:
   - `installation` for CLI, package, authentication, or context setup
   - `quick-start` for project initialization and the first local workflow
   - `config` for targets, env files, context bindings, and lockfiles
   - `cli` for command syntax, effects, flags, environments, and diagnostics
   - `guides` for CI and troubleshooting
4. Derive the command from the returned page content, not from examples retained in conversation.

Verify all four provenance facts before planning a command. Report them when the user asks about
command availability or the installed contract, or when diagnosing bundle failure, compatibility,
or documentation drift. When outputs are available, report the observed `packageName`,
`packageVersion`, `sourcePackage`, and complete available-page catalog. In a plan where discovery has
not run, name the fields and expected source package but label them unverified; never substitute
reference-bundle values for installed results. Keep routine provenance verification internal when
those facts do not help the user decide or troubleshoot.

Before presenting a remote-changing command, state its selected targets and destination plus every
material implicit mutation, local write, and confirmation documented for the operation. Keep
conditional lifecycle paths separate. For local-only operations, state their non-mutating boundary
concisely instead of enumerating the entire documentation section.

The documentation commands are local and non-mutating. Reload the relevant page when the installed
version changes or when moving to a different kind of operation.

### Help fallback

If `tela workflow docs` is unavailable or its bundle cannot be read:

1. Run `tela --version` and `tela workflow --help`.
2. Use command-group help only to discover registered commands and syntax.
3. Report the documentation failure and recommend updating or repairing the Tela CLI installation.
4. Do not treat registration as proof that a command is implemented, and do not perform `sync`,
   `publish`, or another remote-changing operation from help alone.

Never execute a workflow subcommand merely to probe support. Do not pass `--help` to a workflow
subcommand unless command-group help or bundled docs explicitly guarantee that it is non-executing;
some versions may run the subcommand instead.

## Safety Rules

- Treat `init` as local-only. Preserve existing files and do not contact Tela APIs, create remote
  resources, sync, publish, or write Workflow Code lockfiles.
- Treat `compile` as local/offline and non-mutating. Do not require remote identity or auth, call Tela
  APIs, write state, sync, or publish.
- When multiple compile targets exist and the requested target is unclear, list them and ask one
  focused question before running a command.
- Run `sync` only after the user explicitly requests a remote update and the target scope is clear.
- NEVER run `tela workflow sync` without `[target]` unless the user explicitly asks to sync every
  configured workflow.
- Run `publish` only after the requested target and publication destination are clear.
- NEVER run `tela workflow publish` without `[target]` unless the user explicitly asks to publish
  every configured workflow.
- Never leave a documented publication default implicit. Disclose the default and include the
  corresponding explicit flag in the command. Ask when the installed docs do not establish the
  intended destination.
- NEVER add `--yes` before surfacing the exact confirmation or divergence it would bypass and
  receiving explicit authorization to continue. Authorization for one confirmation does not cover
  another mutation.
- NEVER add an environment-creation flag unless the user explicitly authorizes creating the exact
  named environment for the selected targets. Publishing to an environment does not authorize
  creating it, and `--yes` does not broaden that authorization.
- When asking for additional authorization, state exactly which mutation or confirmation it covers
  and which adjacent documented flags or mutations remain unauthorized.
- Never attempt to create an environment that the installed docs identify as system-managed.
- Never normalize an invalid target or environment name silently. Report the complete installed
  validation rule—not only the part the supplied value violates—including every documented allowed
  form, length or format constraint, and reserved category. Then ask for the intended valid value.
- Keep dotenv selection, publication environment, and Tela Local context distinct according to the
  installed docs. Never switch context or borrow credentials silently.
- Never invent binaries, flags, commands, config properties, environment rules, or lockfile fields.
- Never bypass CLI restrictions with direct Tela API calls unless the user explicitly switches to
  the direct API workflow path.
- Never print env values, tokens, or other credential material.

## Red Flags — Stop

- A remote command omits its positional target without explicit all-target authorization.
- A retry adds `--yes`, an environment-creation flag, or a different context without new
  authorization for that exact action.
- A command appears only in command-group help, the documentation provenance is unexpected, or the
  installed contract is otherwise unclear.
- A proposed recovery broadens the selected targets, destination, or remote mutations.

Any red flag means: stop before execution, report the exact uncertainty or diagnostic, and request
only the clarification or authorization needed to proceed.

## Common Rationalizations

| Rationalization | Why it is wrong | Required action |
|---|---|---|
| “Run sync/publish” authorizes every configured target. | Generic wording does not authorize an all-target remote mutation. | **List targets and ask one focused scope question.** |
| “`--yes` only makes the command non-interactive.” | It can bypass a specific divergence confirmation and does not authorize adjacent mutations. | **Surface the divergence and request explicit continuation authorization.** |
| “Publishing to a named environment also authorizes creating it.” | Publishing and creating an environment are separate remote mutations. | **Request creation authorization for the exact environment and targets.** |
| “The command is listed in `tela workflow --help`, so it is implemented.” | Group help proves registration, not implementation or remote behavior. | **Require the version-matched bundled documentation.** |

## Operational Flow

1. Load the installed documentation and provenance for the requested operation.
2. Inspect the project config, target names, relevant env-file paths, and active context binding
   without printing secrets.
3. Resolve target and environment scope before any mutation. Ask one focused question when scope is
   ambiguous; never infer all-target authorization from plural or generic wording.
4. Build the exact command from the installed docs and prefer `--json`.
5. Before a remote-changing command, enumerate the selected targets, destination, every documented
   implicit lifecycle step, every local write and remote effect, and any confirmation that may be
   required.
6. Run only the authorized scope. Do not add convenience flags preemptively.
7. Report the result and every relevant diagnostic `code`, `severity`, `message`, and `hint`.
8. Stop before any retry that would overwrite divergence, create another resource, change context,
   or broaden scope. Request the specific additional authorization first.

## Diagnostics

Treat JSON diagnostics from a user-authorized operation as the final authority for that execution.
Report each relevant diagnostic separately and reproduce its `code`, `severity`, `message`, and
`hint` verbatim before asking for confirmation or proposing a retry. Do not paraphrase, merge, or
truncate `message` or `hint`. Never hide warnings, guess around a missing file or binding, or replace
a CLI-provided hint with remembered behavior.

When bundled docs, command-group help, and runtime diagnostics disagree:

1. record the installed CLI and documentation package versions
2. use bundled docs rather than unversioned or `latest` documentation
3. use command-group help only for discovery
4. trust runtime diagnostics for the attempted operation
5. stop before a mutation whose contract remains unclear

## Examples

### Discover support safely

<good-example>
Run `tela workflow docs --json`, verify its package provenance, and read
`tela workflow docs cli --json`. If the bundle is unavailable, run only `tela --version` and
`tela workflow --help`, report the installation problem, and do not probe or execute a remote
command.
</good-example>

<bad-example>
Run `tela workflow publish --help` and conclude that publish is safe because its name appears.

**Why bad:** A subcommand may execute despite `--help`, and command registration alone does not
prove implementation or remote behavior.
</bad-example>

### Preserve remote authorization boundaries

<good-example>
The project has `invoice-processing` and `payment-reminders`. The user asks to publish to `staging`
without naming a target. List both targets and ask one focused scope question. After the user selects
`invoice-processing`, derive the target-scoped command from the bundled docs without adding `--yes`
or an environment-creation flag. If the CLI later reports that `staging` is missing, reproduce the
diagnostic fields and request creation authorization for only that environment and target.
</good-example>

<bad-example>
Run a targetless publish with `--yes` and an environment-creation flag to avoid later prompts.

**Why bad:** It broadens target scope and pre-authorizes two independent remote decisions the user
has not made.
</bad-example>