Swamp Workflow Skill

Work with swamp workflows through the CLI. All commands support --json for machine-readable output.

CRITICAL: Workflow Creation Rules

• Never generate workflow IDs — no uuidgen, crypto.randomUUID(), or manual UUIDs. Swamp assigns IDs automatically via swamp workflow create.
• Never write a workflow YAML file from scratch — always use swamp workflow create <name> --json first, then edit the scaffold at the returned path, preserving the assigned id.
• Never modify the id field in an existing workflow file.
• Verify CLI syntax: If unsure about exact flags or subcommands, run swamp help workflow for the complete, up-to-date CLI schema.

Correct flow: swamp workflow create <name> --json → edit the YAML → validate → run.

Quick Reference

Repository Structure

Swamp uses a dual-layer architecture:

• Data directory (/.swamp/) - Internal storage organized by entity type
• Logical views (/workflows/) - Human-friendly symlinked directories

/workflows/{workflow-name}/
  workflow.yaml → ../.swamp/workflows/{id}.yaml
  runs/
    latest → {most-recent-run}/
    {timestamp}/
      run.yaml → ../.swamp/workflow-runs/{id}/{run-id}.yaml

Use swamp repo index to rebuild if symlinks become out of sync.

IMPORTANT: Always Get Schema First

Before creating or editing a workflow file, ALWAYS get the schema first:

bash
1swamp workflow schema get --json

Output shape:

json
1{
2  "workflow": {/* JSON Schema for top-level workflow */},
3  "job": {/* JSON Schema for job objects */},
4  "jobDependency": {/* JSON Schema for job dependency with condition */},
5  "step": {/* JSON Schema for step objects */},
6  "stepDependency": {/* JSON Schema for step dependency with condition */},
7  "stepTask": {/* JSON Schema for task (model_method or workflow) */},
8  "triggerCondition": {/* JSON Schema for dependency conditions */}
9}

Create a Workflow

bash
1swamp workflow create my-deploy-workflow --json

Output shape:

json
1{
2  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
3  "name": "my-deploy-workflow",
4  "path": "workflows/workflow-3fa85f64-5717-4562-b3fc-2c963f66afa6.yaml"
5}

The id is auto-assigned and must not be changed. Edit the YAML file at the returned path to add jobs and steps.

Example workflow file:

yaml
1id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
2name: my-deploy-workflow
3description: Deploy workflow with build and deploy jobs
4version: 1
5inputs:
6  properties:
7    environment:
8      type: string
9      enum: ["dev", "staging", "production"]
10      description: Target deployment environment
11    replicas:
12      type: integer
13      default: 1
14  required: ["environment"]
15jobs:
16  - name: build
17    description: Build the application
18    steps:
19      - name: compile
20        description: Compile source code
21        task:
22          type: model_method
23          modelIdOrName: build-runner
24          methodName: build
25  - name: deploy
26    description: Deploy the application
27    dependsOn:
28      - job: build
29        condition:
30          type: succeeded
31    steps:
32      - name: upload
33        description: Upload artifacts
34        task:
35          type: model_method
36          modelIdOrName: deploy-service
37          methodName: deploy
38          inputs:
39            environment: ${{ inputs.environment }}

Edit a Workflow

Recommended: Use swamp workflow get <name> --json to get the file path, then edit directly with the Edit tool, then validate with swamp workflow validate <name> --json.

Alternative methods:

• Interactive: swamp workflow edit my-workflow (opens in system editor)
• Stdin: cat updated.yaml | swamp workflow edit my-workflow --json

Run swamp repo index if search results seem stale after editing.

Delete a Workflow

Delete a workflow and all its run history.

bash
1swamp workflow delete my-workflow --json

Output shape:

json
1{
2  "deleted": true,
3  "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
4  "workflowName": "my-workflow",
5  "runsDeleted": 5
6}

Validate Workflows

Validate against schema and check for errors.

bash
1swamp workflow validate my-workflow --json
2swamp workflow validate --json  # Validate all

Output shape (single):

json
1{
2  "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
3  "workflowName": "my-workflow",
4  "validations": [
5    { "name": "Schema validation", "passed": true },
6    { "name": "Unique job names", "passed": true },
7    { "name": "Valid job dependency references", "passed": true },
8    { "name": "No cyclic job dependencies", "passed": true }
9  ],
10  "passed": true
11}

Run a Workflow

bash
1swamp workflow run my-workflow --json
2swamp workflow run my-workflow --input environment=production --json
3swamp workflow run my-workflow --input environment=production --input replicas=3 --json
4swamp workflow run my-workflow --input '{"environment": "production"}' --json  # JSON also supported
5swamp workflow run my-workflow --input-file inputs.yaml --json
6swamp workflow run my-workflow --last-evaluated --json  # Use pre-evaluated workflow

Options:

Output shape:

json
1{
2  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
3  "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
4  "workflowName": "my-workflow",
5  "status": "succeeded",
6  "jobs": [
7    {
8      "name": "main",
9      "status": "succeeded",
10      "steps": [
11        {
12          "name": "example",
13          "status": "succeeded",
14          "duration": 2,
15          "dataArtifacts": [
16            {
17              "dataId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
18              "name": "output",
19              "version": 1
20            }
21          ]
22        }
23      ],
24      "duration": 2
25    }
26  ],
27  "duration": 5,
28  "path": "workflows/workflow-3fa85f64-5717-4562-b3fc-2c963f66afa6/workflow-7c9e6679-7425-40de-944b-e07fc1f90ae7-timestamp.yaml"
29}

Workflow History

Search Run History

bash
1swamp workflow history search --json
2swamp workflow history search "deploy" --json

Output shape:

json
1{
2  "query": "",
3  "results": [
4    {
5      "runId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
6      "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
7      "workflowName": "my-workflow",
8      "status": "succeeded",
9      "startedAt": "2025-01-15T10:30:00Z",
10      "duration": 5
11    }
12  ]
13}

Get Latest Run

bash
1swamp workflow history get my-workflow --json

Output shape:

json
1{
2  "runId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
3  "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
4  "workflowName": "my-workflow",
5  "status": "succeeded",
6  "startedAt": "2025-01-15T10:30:00Z",
7  "completedAt": "2025-01-15T10:30:05Z",
8  "jobs": [/* job execution details */]
9}

View Run Logs

bash
1swamp workflow history logs my-workflow --json        # Latest run logs
2swamp workflow history logs 7c9e6679-7425-40de-944b-e07fc1f90ae7 --json            # Specific run logs
3swamp workflow history logs 7c9e6679-7425-40de-944b-e07fc1f90ae7 build.compile --json  # Specific step logs

Output shape:

json
1{
2  "runId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
3  "step": "build.compile",
4  "logs": "Building application...\nCompilation complete.",
5  "exitCode": 0
6}

Workflow Inputs

Workflows can define an inputs schema for parameterization. Inputs are validated against a JSON Schema before execution.

Input Schema

yaml
1inputs:
2  properties:
3    environment:
4      type: string
5      enum: ["dev", "staging", "production"]
6      description: Target environment
7    replicas:
8      type: integer
9      default: 1
10  required: ["environment"]

Supported Types

Using Inputs in Expressions

Reference inputs with ${{ inputs.<name> }}:

yaml
1steps:
2  - name: deploy
3    task:
4      type: model_method
5      modelIdOrName: deploy-service
6      methodName: deploy
7      inputs:
8        environment: ${{ inputs.environment }}

Evaluate Workflows

Evaluate expressions without executing. CEL expressions are resolved; vault expressions remain raw for runtime resolution.

bash
1swamp workflow evaluate my-workflow --json
2swamp workflow evaluate my-workflow --input environment=dev --json
3swamp workflow evaluate --all --json

Key behaviors:

• CEL expressions (${{ inputs.X }}, ${{ model.X.resource... }}) are resolved
• forEach steps are expanded into concrete steps with resolved inputs
• Vault expressions (${{ vault.get(...) }}) remain raw for runtime resolution
• Output saved to .swamp/workflows-evaluated/ for --last-evaluated use

Allow Failure

Steps can be marked with allowFailure: true so their failure does not fail the job or workflow. The step is still recorded as failed, but the failure is not propagated.

yaml
1steps:
2  - name: optional-check
3    allowFailure: true
4    task:
5      type: model_method
6      modelIdOrName: checker
7      methodName: validate

• Step status remains failed with its error message
• The run output includes allowedFailure: true on the step
• Downstream dependsOn: succeeded steps will skip; dependsOn: completed steps will run

Step Task Types

Steps support two task types:

model_method - Call a method on a model:

yaml
1task:
2  type: model_method
3  modelIdOrName: my-model
4  methodName: run
5  inputs: # Optional: pass values to the model
6    key: ${{ inputs.value }}

workflow - Invoke another workflow (waits for completion):

yaml
1task:
2  type: workflow
3  workflowIdOrName: child-workflow
4  inputs: # Optional: pass inputs to the child workflow
5    key: value

Nested workflows have a max depth of 10 and cycle detection is enforced.

Working with Vaults

Access secrets using vault expressions. See swamp-vault skill for details.

yaml
1apiKey: ${{ vault.get(vault-name, secret-key) }}
2dbPassword: ${{ vault.get(prod-secrets, DB_PASSWORD) }}

Workflow Example

End-to-end workflow creation:

1. Get schema: swamp workflow schema get --json
2. Create: swamp workflow create my-task --json
3. Edit: Add jobs and steps to the YAML file
4. Validate: swamp workflow validate my-task --json
5. Fix any errors and re-validate
6. Run: swamp workflow run my-task --json

When to Use Other Skills

References

• CI/CD integration: See swamp-repo skill's references/ci-integration.md for installing swamp in CI and GitHub Actions examples
• Nested workflows: See references/nested-workflows.md for full examples of workflows calling other workflows, forEach with workflows, and nesting limitations
• Expressions, forEach, and data tracking: See references/expressions-and-foreach.md for forEach iteration patterns, CEL expressions, environment variables, and data artifact tagging
• Data chaining and lifecycle workflows: See references/data-chaining.md for model.* vs data.latest() expression guidance, delete/update workflow ordering, and command/shell chaining examples
• Execution drivers: See references/execution-drivers.md for per-step driver overrides and Docker execution