---
name: zo-swamp
description: >
  Unified Zo skill for running Swamp automation workflows on Zo Computer.
  Swamp is an AI-agent-driven automation framework (https://swamp.club) that
  provides typed models, DAG workflows, versioned data, and CEL-based querying.
  Use this skill when the user asks to: run a swamp workflow, create a model,
  query stored data, manage vaults, troubleshoot swamp issues, or set up a new
  swamp pipeline on Zo.
metadata:
  author: cashlessconsumer.zo.computer
  version: 1.0.0
  requires:
    - swamp CLI (/usr/local/bin/swamp via Deno)
    - deno (installed at /root/.deno/bin/deno)
  repoDir: /home/workspace
---
# zo-swamp — Swamp Automation on Zo Computer

## Overview

Swamp is an AI-agent-driven automation framework. On Zo, it manages **typed models**, **DAG workflows**, **versioned data**, and **CEL-based querying** — all stored in `.swamp/`, `models/`, and `workflows/` inside the workspace repo.

**Prerequisites**: Deno + Swamp CLI are installed. Swamp repo is initialized at `/home/workspace` with `.swamp.yaml`.

## Quick Reference

### Run a workflow
```bash
# Basic run
swamp workflow run <workflow-name> --repo-dir /home/workspace

# Run with input variables
swamp workflow run <workflow-name> --repo-dir /home/workspace --input key=value --input key2=json_value

# Run a specific model method directly (no workflow needed)
swamp model run <model-name> <method-name> --repo-dir /home/workspace
```

### Create a model
```bash
# Scaffold a new model (supports: command/shell, http-request, openai-chat, anthropic-chat, ollama-chat, etc.)
swamp model create <type> <name> --repo-dir /home/workspace

# Common types: command/shell, http-request, openai-chat, anthropic-chat, ollama-chat, opencode-zen
```

### Validate
```bash
swamp model validate <model-name>    # validate a model
swamp workflow validate <workflow>   # validate a workflow
swamp doctor workflows               # validate ALL workflows
swamp doctor models                  # validate ALL models
```

### Data operations
```bash
# List all data for a workflow run
swamp data list --workflow "<workflow-name>"

# Get specific data item
swamp data get --model "<model-name>" "<data-name>"

# Query with CEL predicate
swamp data query --workflow "<workflow-name>" --predicate 'name == "result" && version > 0'

# Search across all data
swamp data search "<search-term>"

# View data versions
swamp data versions --model "<model-name>" "<data-name>"

# Rename / delete / garbage collect
swamp data rename <old-name> <new-name> --model "<model-name>"
swamp data delete <data-name> --model "<model-name>"
swamp data gc                           # garbage collect expired data
```

### Vault operations (encrypted secrets)
```bash
swamp vault create <type> <name>         # Create vault (types: env, dotfile, aws, gcp, azure)
swamp vault put <vault> <key>            # Write secret (reads from stdin)
swamp vault read <vault> <key>           # Read secret
swamp vault list-keys <vault>            # List all keys
swamp vault migrate <vault> <new-type>   # Migrate vault type
```

### Workflow YAML Schema
```yaml
id: <uuid>
name: <workflow-name>
tags: {}
jobs:
  - name: <job-name>
    description: What this job does
    steps:
      - name: <step-name>
        description: What this step does
        task:
          type: model_method        # model_method | model_input | model_definition | nested_workflow
          modelIdOrName: <model>   # model name or UUID
          methodName: execute       # method to call
        dependsOn: []              # or: [{job: <name>, condition: {type: succeeded|failed|always}}]
        weight: 0
        allowFailure: false
        forEach: null              # optional: iterate over data array
        trigger:
          type: condition          # condition | always | manual
          predicate: 'true'        # CEL expression
    dependsOn: []                  # inter-job dependencies
    weight: 0
version: 1
```

### Model YAML Schema (command/shell example)
```yaml
type: command/shell
typeVersion: 2026.02.09.1
id: <uuid>
name: <model-name>
version: 1
tags:
  pipeline: <category>
  schedule: daily
globalArguments: {}
methods:
  execute:
    arguments:
      run: <shell-command>
      workingDir: /home/workspace
      timeout: 120000       # ms
      ignoreExitCode: true  # don't fail on non-zero exit
```

### CEL Expression Context
Available variables in predicates and expressions:
- `model` — current model object
- `workflow` — current workflow object
- `job` — current job object
- `step` — current step object
- `result` — model output resource
- `data` — data layer access function
- `env` — environment variables
- `vault` — vault access function

### Data Chaining
```bash
# Get result from model A, pass as input to model B
swamp model run model-a execute
swamp data get --model model-a result > /tmp/input.json
swamp workflow run pipeline-b --repo-dir /home/workspace --input "@/tmp/input.json"
```

## Existing Models on This Zo

| Model | Type | What it does |
|---|---|---|
| `skills-backup` | command/shell | Syncs personal skills → CCAgentOrg/zo-skills on GitHub |
| `koodous-sdk-alert` | command/shell | Polls Koodous for new surveillance SDK detections |
| `free-model-ranking` | command/shell | Refreshes + ranks free-tier AI models across 4 providers |
| `wikipedia-dyk-check` | command/shell | Queries DYK DuckDB for coverage gaps |

## Existing Workflows on This Zo

| Workflow | Description |
|---|---|
| `skills-backup` | Daily skills backup to GitHub |
| `koodous-daily-alert` | Daily Koodous SDK alert + landscape |
| `free-model-ranking` | Daily free model refresh + ranking |
| `wikipedia-dyk-check` | Daily DYK database status check |
| `daily-ops-pipeline` | All 4 above as a dependency DAG |

## Common Patterns

### Run workflow and send results to Telegram
1. `swamp workflow run <name> --repo-dir /home/workspace`
2. `swamp data get --model <model> result`
3. Send the result text via `send_telegram_message`

### Create a new model from scratch
1. `swamp model create command/shell <name> --repo-dir /home/workspace`
2. Edit the scaffolded YAML in `models/command/shell/<uuid>.yaml`
3. `swamp model validate <name>`
4. Create a workflow: `swamp workflow create <name> --repo-dir /home/workspace`
5. Edit `workflows/workflow-<uuid>.yaml` to reference the model
6. `swamp doctor workflows`

### Troubleshooting
- `swamp doctor workflows` — validate all workflow YAML schemas
- `swamp doctor models` — validate all model definitions
- `swamp model validate <name>` — check a specific model
- Check model output: `swamp data get --model <model> result`
- Check logs: `swamp data get --model <model> log`
- Check workflow summary: `swamp data get --workflow <name> report-swamp-workflow-summary`

## Swamp-Generated Skills (deep reference)

Swamp auto-generates detailed skills in `.agents/skills/swamp-*/`:
- `swamp-data` — Data outputs, querying, GC, versions
- `swamp-getting-started` — Setup, first workflow, config
- `swamp-model` — Model CRUD, validation, execution
- `swamp-vault` — Vault management, secret storage
- `swamp-workflow` — Workflow CRUD, dependencies, triggers, forEach

Consult these for deeper reference when needed.

## References

- Full manual: https://swamp.club/manual
- Workflows reference: https://swamp.club/manual/reference/workflows
- Model definitions: https://swamp.club/manual/reference/model-definitions
- Data outputs: https://swamp.club/manual/reference/data-outputs
- Data querying: https://swamp.club/manual/reference/data-querying
- Vaults: https://swamp.club/manual/reference/vaults
- How Swamp works: https://swamp.club/manual/explanation/how-swamp-works
- GitHub: https://github.com/systeminit/swamp