write-playbook

What this skill does

# Write Playbook

## Goal

Turn a user request into a valid Playbook YAML that can be applied in Mission Control.

## How to Use

1. Identify the action type(s) the user needs (exec, http, sql, gitops, github, azureDevopsPipeline, notification, pod, logs, ai).
2. Ask only the minimum clarifying questions required to produce correct YAML (target config types, credentials, parameters, trigger mode).
3. Produce a single Playbook YAML in a fenced code block. Keep it minimal and runnable.
4. If the user mentions secrets, always use connection references or secret refs (do not inline sensitive values).
5. If a request cannot be expressed in a single action type, chain multiple actions in the `actions` list.

## Inputs Checklist

- What the playbook should do (action type)
- Target config types (for `configs:` selector)
- Credentials source (connection name or secret ref)
- Parameters the user should provide at run time
- Trigger mode: manual (default), event-driven (`on:`), or webhook

## Output Rules

- Output YAML only, in a single code block.
- Use `apiVersion: mission-control.flanksource.com/v1` and `kind: Playbook`.
- Set `metadata.name` to a short, unique slug.
- Always include the schema comment: `# yaml-language-server: $schema=https://raw.githubusercontent.com/flanksource/duty/main/schema/openapi/playbook.schema.json`

## Quick Decision Tree

Use this to pick the right action type:

1. **Run a shell command (kubectl, helm, scripts)?** → `exec`
2. **Call an external HTTP API?** → `http`
3. **Run a SQL query?** → `sql`
4. **Create a git commit / PR?** → `gitops`
5. **Trigger a GitHub Actions workflow?** → `github`
6. **Trigger an Azure DevOps pipeline?** → `azureDevopsPipeline`
7. **Send a notification (Slack, email, Teams)?** → `notification`
8. **Run a container / pod?** → `pod`
9. **Query logs (Loki, CloudWatch, OpenSearch, K8s)?** → `logs`
10. **AI-powered diagnosis or analysis?** → `ai`

## Golden Rules

1. Every action must have a unique `name` field.
2. Use `$()` delimiters for Go templates (NOT `{{ }}`).
3. For shell scripts that use `$()` for subshells, switch delimiters:
   ```bash
   # gotemplate: left-delim=$[[ right-delim=]]
   ```
4. Use `connections.fromConfigItem: '$(.config.id)'` for exec actions that need the config item's cluster context.
5. Reference parameters with `$(.params.<name>)` and config with `$(.config.name)`, `$(.config.tags.namespace)`, etc.
6. For multi-agent setups, use dynamic `runsOn`:
   ```yaml
   runsOn:
     - "$(if .agent)$(.agent.id)$(else)local$(end)"
   ```
7. Chain multiple actions in order; use `if: success()` to gate on previous step success.
8. Set `timeout` on long-running actions (default is 30s).

## Template Context Variables

| Variable | Description | Example |
| --- | --- | --- |
| `.config.id` | Config item UUID | `$(.config.id)` |
| `.config.name` | Config item name | `$(.config.name)` |
| `.config.type` | Full type (e.g. `Kubernetes::Deployment`) | `$(.config.type)` |
| `.config.config_class` | Short class (e.g. `Deployment`) | `$(.config.config_class)` |
| `.config.tags.namespace` | Kubernetes namespace from tags | `$(.config.tags.namespace)` |
| `.config.config` | Raw JSON config object | `$(.config.config.spec.replicas)` |
| `.config.config \| jq "..."` | JQ query on config JSON | `$(.config.config \| jq ".spec.template.spec.containers[0].name")` |
| `.config.config \| toJSON \| neat \| json \| toYAML` | Clean YAML of config | Used in code editor defaults |
| `.params.<name>` | User-supplied parameter value | `$(.params.replicas)` |
| `.user.name` | Current user display name | `$(.user.name)` |
| `.user.email` | Current user email | `$(.user.email)` |
| `.agent.id` | Agent identifier | `$(.agent.id)` |
| `.run.id` | Current playbook run UUID | `$(.run.id)` |
| `.git.git.url` | Git repo URL from Flux origin | `$(.git.git.url)` |
| `.git.git.file` | File path from Flux origin | `$(.git.git.file)` |
| `getLastAction.result` | Previous action result | `$(getLastAction.result.stdout)` |
| `getLastAction.result.slack` | Slack-formatted result from AI action | `$(getLastAction.result.slack)` |
| `random.Alpha 8` | Random alphanumeric string | `$(random.Alpha 8)` |
| `time.Now.Format "..."` | Current time formatted | `$(time.Now.Format "2006-01-02")` |
| `strings.ToLower` | Lowercase string | `$(.config.config_class \| strings.ToLower)` |

## Parameter Types

| Type | Description | Example |
| --- | --- | --- |
| `text` | Single-line text input | Replicas count, names |
| `code` | Multi-line code editor | YAML input, scripts |
| `checkbox` | Boolean toggle | Enable/disable options |
| `list` | Dropdown with options | Time durations, roles |
| `config` | Config item picker | Select a ClusterRole, Namespace |
| `people` | People picker | Select users |
| `team` | Team picker | Select teams |
| `millicores` | CPU input (millicores) | CPU requests/limits |
| `bytes` | Memory input (bytes) | Memory requests/limits |

### Parameter Properties

| Property | Description |
| --- | --- |
| `properties.multiline: 'true'` | Enable multiline for text |
| `properties.size: large` | Large editor for code params |
| `properties.colSpan: 4` | Grid column span (1-12) |
| `properties.options` | Array of `{label, value}` for `list` type |
| `properties.filter` | Resource filter for `config` type |

## Canonical Snippets

### 1) exec — kubectl command

```yaml
apiVersion: mission-control.flanksource.com/v1
kind: Playbook
metadata:
  name: scale-deployment
spec:
  title: Scale
  icon: scale-out
  category: Kubernetes
  description: Scales a deployment using kubectl
  configs:
    - agent: all
      types:
        - Kubernetes::Deployment
        - Kubernetes::StatefulSet
  parameters:
    - name: replicas
      label: Replicas
      type: text
      default: "$(.config.config.spec.replicas)"
  runsOn:
    - "$(if .agent)$(.agent.id)$(else)local$(end)"
  actions:
    - name: kubectl scale
      exec:
        connections:
          fromConfigItem: '$(.config.id)'
        script: |
          kubectl scale $(.config.config_class | strings.ToLower) -n $(.config.tags.namespace) $(.config.name) --replicas=$(.params.replicas)
```

### 2) http — call an external API

```yaml
actions:
  - name: call webhook
    http:
      url: 'https://api.example.com/deploy'
      method: POST
      headers:
        - name: Authorization
          valueFrom:
            secretKeyRef:
              name: api-credentials
              key: token
      body: |
        {"name": "$(.config.name)", "namespace": "$(.config.tags.namespace)"}
      templateBody: true
```

### 3) sql — run a database query

```yaml
actions:
  - name: query database
    sql:
      connection: postgres-connection
      query: |
        SELECT count(*) as total FROM orders WHERE status = 'pending' AND created_at > now() - interval '1 hour'
```

### 4) gitops — create a PR with changes

```yaml
actions:
  - name: create PR
    gitops:
      repo:
        url: '$(.git.git.url)'
        connection: github
        branch: update-$(random.Alpha 8)
      commit:
        author: '$(.user.name)'
        email: '$(.user.email)'
        message: 'chore: update $(.config.name)'
      pr:
        title: 'chore: update $(.config.name)'
      patches:
        - path: '$(.git.git.file)'
          yq: |
            select(.metadata.name=="$(.config.config | jq ".metadata.name")").spec.replicas = $(.params.replicas)
```

### 5) github — trigger a workflow

```yaml
actions:
  - name: trigger deploy workflow
    github:
      repo: org/my-repo
      username: deploy-bot
      token:
        valueFrom:
          secretKeyRef:
            name: github-token
            key: token
      workflows:
        - id: deploy.yml
          ref: main
          input: '{"environment": "$(.params.environment)"}'
```

### 6) azureDevopsPipeline — trigger a pipeline

```yaml
actions:
  - name: trigger build
    azureDevopsPipeline:
      org: my-org
      project: my-project
      token:
        valueFro