/asc-workflow

name: asc-workflow
description: Define, validate, run, resume, and audit repo-local multi-step automations with current `asc workflow` and `.asc/workflow.json`, including step outputs and safe release/TestFlight workflows.

asc workflow

Use this skill when you need lane-style automation inside the CLI using:

• `asc workflow validate`
• `asc workflow list`
• `asc workflow run`

Workflows are repo-local automation files. They run trusted shell commands, stream step output to stderr, and keep stdout as machine-readable JSON.

Command discovery

Always verify flags with:

asc workflow --help
asc workflow validate --help
asc workflow list --help
asc workflow run --help

End-to-end flow

1. Author `.asc/workflow.json`. 2. Validate structure and references:

asc workflow validate

3. Discover public workflows:

asc workflow list
asc workflow list --all

4. Preview execution:

asc workflow run --dry-run beta BUILD_ID:123456789 GROUP_ID:abcdef

5. Execute:

asc workflow run beta BUILD_ID:123456789 GROUP_ID:abcdef

6. If a recoverable run fails, resume with the run ID from the JSON result:

asc workflow run release --resume "release-20260312T120000Z-deadbeef"

Do not pass extra `KEY:VALUE` params with `--resume`; the saved workflow file, params, and persisted outputs are reused.

File location and format

• Default path: `.asc/workflow.json`
• Override path: `asc workflow run --file ./path/to/workflow.json <name>`
• JSONC comments are supported.
• Top-level hooks: `before_all`, `after_all`, `error`
• Workflow keys: `description`, `private`, `env`, `steps`
• Step forms:
• string shorthand: `"echo hello"`
• `run` shell command
• `workflow` sub-workflow call
• `name` label
• `if` conditional var name
• `with` env overrides for workflow-call steps
• `outputs` map for JSON stdout extraction from named run steps

Outputs

Run steps can declare outputs. The command must emit JSON on stdout, so pass `--output json` for `asc` commands that produce outputs.

Output references use:

${steps.step_name.OUTPUT_NAME}

Rules:

• A step that declares `outputs` must have a reference-safe `name`.
• Outputs are allowed on `run` steps, not workflow-call steps.
• Output-producing names must be unique across workflows that can execute together in the same run graph.
• Persisted outputs are stored in workflow run state, so do not map secrets into outputs.

Runtime params

`asc workflow run <name> [KEY:VALUE ...]` supports both separators:

asc workflow run beta VERSION:2.1.0
asc workflow run beta VERSION=2.1.0

Repeated keys are last-write-wins. In shell commands, reference params through shell expansion like `$VERSION`.

Env precedence

Main workflow run:

definition.env < workflow.env < CLI params

Sub-workflow call with `with`:

sub-workflow env < caller env and params < step with

Conditionals

Add `"if": "VAR_NAME"` to a step. Truthy values are `1`, `true`, `yes`, `y`, and `on`, case-insensitive. Lookup checks merged workflow env/params first, then process environment.

Example workflow

{
  "env": {
    "APP_ID": "123456789",
    "VERSION": "1.0.0",
    "GROUP_ID": ""
  },
  "before_all": "asc auth status",
  "after_all": "echo workflow_done",
  "error": "echo workflow_failed",
  "workflows": {
    "beta": {
      "description": "Resolve the latest build and distribute it to TestFlight",
      "steps": [
        {
          "name": "resolve_build",
          "run": "asc builds info --app $APP_ID --latest --platform IOS --output json",
          "outputs": {
            "BUILD_ID": "$.data.id"
          }
        },
        {
          "name": "list_groups",
          "run": "asc testflight groups list --app $APP_ID --limit 20 --output json"
        },
        {
          "name": "add_build_to_group",
          "if": "GROUP_ID",
          "run": "asc builds add-groups --build-id ${steps.resolve_build.BUILD_ID} --group $GROUP_ID"
        }
      ]
    },
    "release": {
      "description": "Validate, stage, and submit an App Store version",
      "steps": [
        {
          "name": "validate",
          "run": "asc validate --app $APP_ID --version $VERSION --platform IOS --output json"
        },
        {
          "name": "stage",
          "run": "asc release stage --app $APP_ID --version $VERSION --build $BUILD_ID --metadata-dir ./metadata/version/$VERSION --confirm --output json"
        },
        {
          "name": "submit",
          "if": "SUBMIT_FOR_REVIEW",
          "run": "asc review submit --app $APP_ID --version $VERSION --build $BUILD_ID --confirm --output json"
        }
      ]
    },
    "publish-appstore": {
      "description": "High-level upload plus App Store review submission",
      "steps": [
        {
          "name": "publish",
          "run": "asc publish appstore --app $APP_ID --ipa ./build/MyApp.ipa --version $VERSION --wait --submit --confirm --output json"
        }
      ]
    }
  }
}

Useful invocations

asc workflow validate | jq -e '.valid == true'
asc workflow list --pretty
asc workflow list --all --pretty
asc workflow run --dry-run beta BUILD_ID:123 GROUP_ID:grp_abc
asc workflow run beta BUILD_ID:123 GROUP_ID:grp_abc | jq -e '.status == "ok"'
asc workflow run release BUILD_ID:123 SUBMIT_FOR_REVIEW:true
asc workflow run release --resume "release-20260312T120000Z-deadbeef"

Safety rules

• Treat `.asc/workflow.json` like code; only run trusted workflow files.
• Avoid running workflows from untrusted PRs with secrets.
• Keep workflow files in version control.
• Validate first, dry-run next, then run.
• Use explicit IDs and `--confirm` for mutating steps.
• Use `asc validate`, `asc release stage`, `asc review submit`, and `asc publish appstore`; do not use removed submission commands.