build-workflow

Files (1)

• SKILL.md

SKILL.md (first lines)

# ArchAstro Workflow Builder

Create, edit, and deploy workflows — multi-step processes that agents execute via routines.

This skill assumes the ArchAstro CLI is already installed and authenticated. Install or upgrade `archastro` if missing, and run `archastro auth login` if not authenticated.

## What is a Workflow?

A workflow is a directed graph of nodes that defines a multi-step process. Use the dedicated top-level workflow resource for authoring: `archastro list workflows`, `describe workflow`, `create workflow`, `update workflow`, `validate workflow`, and `describe workflowdocs`. Workflows are then attached to agent routines for execution.

## Always Start with State

Every invocation must begin by understanding the current context:

```
archastro auth status
archastro list agents
```

Determine:
- Which agent will run this workflow?
- Is this a new workflow or an update to an existing one?
- What trigger should start it? (schedule, webhook, manual, message event)

## Routing

### CLI not installed or too old

Before any workflow work, verify the CLI:

- Read `plugin-compatibility.json` from the plugin root.
- Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`.
- Run `archastro --version`. If missing or older than the resolved minimum, instruct the user to install or upgrade `archastro`.
- If authentication or app selection is missing, instruct the user to run `archastro auth login`.

### User wants to create a new workflow

**Phase 1: Gather requirements**

Understand the workflow before writing any config:
- What triggers it? (cron schedule, webhook, message, manual)
- What are the steps? (in plain language)
- Are there branches or conditions?
- Does it need to call external APIs?
- Does it need to send emails, Slack messages, or other notifications?
- Does it loop over a collection?

**Discover available events** to understand what can trigger the workflow and what data the trigger provides:
```
archastro list events
```

Once the user picks an event type, show them the payload schema so they know what `$` contains in downstream scripts:
```
archastro describe event <event-name>
```

This returns the JSON schema and a sample payload. The payload fields are accessible via `$` in scripts (e.g., `$.thread_id`, `$.message.content`).

**Phase 2: Scaffold the workflow**

Use the top-level workflow commands, not `describe configsample`/`validate config`, for the normal authoring loop.

Create a workflow from a local JSON file:
```
archastro create workflow --id my-workflow --file ./workflows/my-workflow.json
```

Or let the CLI start from its built-in sample if you do not pass `--graph` or `--file`:
```
archastro create workflow --id my-workflow
```

**Phase 3: Author the workflow**

A workflow is a `WorkflowGraph` JSON config under the hood, but the user-facing authoring path should go through the top-level workflow commands.

Start with the graph returned by `create workflow --id my-workflow` when no file is supplied, inspect it with `describe workflow my-workflow --output json`, and edit its graph locally. This creates a persisted scaffold; use `update workflow` for subsequent changes rather than creating it again. Keep the graph schema, node kinds, edges, and embedded data references aligned with the live reference.

Use the live workflow docs when the graph shape is unclear:
```
archastro describe workflowdocs
```

If a command is missing, verify the CLI version and upgrade through the installation route before continuing.

### Available node types

Do not hard-code a node taxonomy in this skill. The supported graph/node model is owned by the workflow implementation and `archastro describe workflowdocs`.

**Phase 4: Write supporting scripts**

If the workflow needs script logic, author and validate that script first. Route to the `build-script` skill for detailed script authoring guidance, or get the reference directly:
```
archastro describe scriptdocs
archastro describe configsample Script
```

**Phase 5: Validate**

Validate the workflow graph through the dedicated workflow command:
```
archastro validate workflow --file ./workflows/my-workflow.json
```

Validate any referenced scripts:
```
archastro validate script --file ./scripts/my-script.agentscript
```

Fix any validation errors before deploying.

**Phase 6: Deploy**

The scaffold already exists from Phase 2. Persist the validated changes with an update:
```
archastro update workflow my-workflow --file ./workflows/my-workflow.json
```

From ArchAstro/archastro, MIT.

More from ArchAstro/archastro