Writing Task Templates

Writing Task Templates

A task template is a reusable multi-step workflow with per-step persona assignments. Drop a markdown file into <userData>/clusterspace-data/config/tasks/<category>/<id>.md and it becomes available to reference from chat or goals.

Source: src/main/config-loader.ts. Defaults: resources/defaults/tasks/.

---

File format

---
id: backup-and-deploy
name: "Backup and Deploy"
category: operations
description: "Snapshot the DB, deploy the app, verify health"
assignedPersonas:
  - admin
  - monitor
successCriteria: "App is deployed at v2.0 and curl http://localhost/health returns 200"
---

## Overview

This template covers the standard production deploy: take a DB snapshot, deploy the new version, run health checks.

## Steps

### Step 1: Pre-flight check
**Persona**: admin
**Action**: Verify disk space, service status, and recent backup count.
**Success criterion**: All of: `df -h | grep -q '[0-9]\{2\}%'` (>10% free), `systemctl is-active myapp`, `ls /backups/ | wc -l` ≥ 7.
**On failure**: Stop. Report which check failed.

### Step 2: Backup database
**Persona**: admin
**Action**: Run `pg_dump -Fc -f /backups/pre-deploy-$(date +%F).dump myapp`.
**Success criterion**: Backup file exists and is > 0 bytes.

### Step 3: Deploy new version
**Persona**: admin
**Action**: Pull latest image, restart service via `systemctl restart myapp`.
**Success criterion**: Service is active and version endpoint reports v2.0.

### Step 4: Wait for warm-up
**Persona**: monitor
**Action**: Sleep 30s then check `/metrics` endpoint for request handling.
**Success criterion**: `/metrics` returns 200 with non-zero `requests_total`.

### Step 5: Health verification
**Persona**: monitor
**Action**: Curl `/health` three times with 5s gaps; all must return 200.
**Success criterion**: All three return 200.

### Step 6: Smoke test
**Persona**: monitor
**Action**: Run the `smoke.sh` script in the repo.
**Success criterion**: Exit code 0.

## Rollback

If any step 3+ fails:
1. Restore the snapshot from step 2.
2. Revert to previous version.
3. Re-verify health.
4. Alert the operator with the failure detail.

---

Frontmatter fields

Field	Required	Purpose
id	yes	Unique identifier. Used in chat references like "run the backup-and-deploy template"
name	yes	Display name
category	yes	Top-level grouping (development, operations, etc.) — determines the subdirectory under tasks/
description	recommended	One-line summary
assignedPersonas	yes	List of persona ids the template uses
successCriteria	yes	Plain-English overall success — also feeds into [[Goal-Runner-Overview

The frontmatter is the contract; the body is the human-readable spec the executing persona will read and follow.

---

Step authoring conventions

The defaults use the structure shown above (Overview → Steps → Rollback). Personas read the body in full when invoked; concrete sections (success criterion, on-failure) help them act predictably.

For each step:

• Persona — who executes this step. Must be in assignedPersonas.
• Action — what to do. Be concrete. Include exact commands where possible.
• Success criterion — how to know it worked. The persona should use [[AI-Tools-Reference|verify_step]] with this criterion.
• On failure (optional) — what to do if the criterion fails.

---

Three ways to use a template

1. Reference from chat

Open the AI chat panel and type:

Run the backup-and-deploy template. Target environment: staging.

The active persona reads the template (you may need to paste its body, or have a tool that fetches it by id — see below), then executes step-by-step.

2. Wrap as a goal

Start a Starting-a-Goal with:

• Goal: "Execute the backup-and-deploy task template against staging."
• Success criterion: shell matching the template's successCriteria (e.g., curl -sf http://staging/health && curl -sf http://staging/version | grep v2.0)
• Policy: write_local or network_write depending on the steps

The goal runner drives the loop until verification passes.

3. Multi-pane orchestration

The AI can call create_goal (a tool, not the runner) with the template's assignedPersonas distributed across multiple panes — one per persona. Each pane's agent gets the template body as context and executes its assigned steps.

---

Loading the template body into the model's context

Templates live as files on disk; the model can't read disk paths directly. Three options:

1. Inline — paste the full template body into your chat message
2. Plugin tool — write a small plugin tool get_task_template(id) that reads the template file and returns the body. See Plugin-Authoring for the pattern.
3. System prompt injection — bake the template body into a persona that's specialized for executing it

Option 2 (plugin tool) scales best for users with many templates.

---

Examples in the defaults

• feature-development in tasks/development/ — 6 steps from branch creation to merge. Personas: builder, reviewer, tester.
• deployment in tasks/operations/ — 6 steps from pre-checks to monitor. Personas: admin, monitor.

Read both for tone and structure.

---

Loading order

1. Built-in defaults from resources/defaults/tasks/
2. User overrides from <userData>/clusterspace-data/config/tasks/
3. User overrides win on id collision

Reload requires app restart.

---

See also

• Task-Templates — what task templates are conceptually
• Writing-Personas — the actors templates assign work to
• Goal-Runner-Overview — making a template autonomous via a goal
• Plugin-Authoring — write a tool to load template bodies on demand
• Agent-Orchestration — multi-pane execution model