Implementation Guide

How to setup Tasklife with OpenClaw / Hermes agents

How the lifecycle process actually works

Tasklife lifecycle settings turn project columns into a lightweight workflow engine. Each column can define where work moves next and what instructions agents or humans should follow when a task is read or updated.

The lifecycle fields

Every project column can carry workflow metadata. The important fields are:

  • lifecycle_enabled — turns lifecycle behavior on for that column
  • lifecycle_start_target_column_id — where work should move when execution starts
  • lifecycle_blocked_target_column_id — where work should move when blocked
  • lifecycle_complete_target_column_id — where work should move when completed
  • lifecycle_has_issues_target_column_id — where work should move when QA or review finds issues
  • lifecycle_get_prompt — instructions for how to handle tasks when reading them in this column
  • lifecycle_put_prompt — instructions for what must happen when updating or handing off tasks from this column

The clean mental model

A lifecycle-enabled column defines both movement and behavior:

  • Movement rules tell the board where a task should go next.
  • Behavior rules tell the acting agent or user what they must do before moving it.

That means the board itself becomes the workflow contract instead of relying on people to remember unwritten conventions.

Recommended setup flow

  1. Create role-specific agents in OpenClaw / Hermes.
  2. Create matching agent users in Tasklife.
  3. Configure webhook delivery or API-driven orchestration.
  4. Write role instructions that map to lifecycle prompts.
  5. Enable lifecycle on the board columns that represent real workflow states.
  6. Smoke test one task all the way through the board.

Real example from production: Project 25

Tasklife project 25 on production already uses lifecycle settings in a practical way. These examples are taken from the live board configuration.

To Do → In Progress

The To Do column has lifecycle enabled with:

  • start target = In Progress
  • blocked target = Blocked

Its GET instructions tell the execution agent to post a START comment, move to the start target if configured, do the work, and never guess missing target columns.

That makes To Do the formal launch point for execution rather than just a passive backlog bucket.

In Progress → To QA

The In Progress column has lifecycle enabled with:

  • blocked target = Blocked
  • complete target = To QA

Its PUT instructions are more technical. Before the task can be handed off, the flow requires:

  • verification with concrete evidence
  • creation of exactly one child QA task
  • child task type = Test
  • assignment of that child task to the QA agent
  • placing that child task in To QA

This is a good example of using lifecycle settings to force a disciplined dev-to-QA handoff instead of relying on a vague “done” status.

To QA → Sal Review or QA Issue

The To QA column has lifecycle enabled with:

  • blocked target = Blocked
  • complete target = Sal Review
  • has-issues target = QA issue

Its GET instructions tell QA to do API-first validation before running the task, post a START comment, and then:

  • on pass: move the QA task to its complete target and move the parent task to Sal Review
  • on fail: move both the QA task and the parent task to QA issue

That is a very strong pattern because it makes QA behavior explicit and repeatable.

QA issue → back to execution

The QA issue column has lifecycle enabled with:

  • start target = In Progress
  • blocked target = Blocked

This creates a clean repair loop: once an issue is acknowledged, execution can resume through the defined start path instead of inventing a one-off workflow each time.

How to write good lifecycle prompts

  • Keep them operational and state-specific.
  • Use GET prompts for execution instructions.
  • Use PUT prompts for handoff and completion requirements.
  • Never rely on unstated board conventions.
  • If a target column is required and missing, instruct the agent not to guess.

Practical checklist

  • Enable lifecycle only on columns that are true workflow states.
  • Set target columns before depending on prompt logic.
  • Make blocked and issue paths explicit.
  • Verify the board through the API after configuration changes.
  • Run a smoke test through To Do → In Progress → To QA → Review / Issue.

How to configure agent webhooks

If you want Tasklife to wake OpenClaw, Hermes, or your own agent runner automatically, configure agent webhooks with the same payload shape and operating model used by Tasklife's built-in task and comment events.

1) Create one Tasklife user per agent role

Use separate Tasklife users for separate operating roles like Coding, QA, or PM. That gives you clean assignment, clean audit trails, and role-specific webhook routing.

  • Create one agent user per role.
  • Assign work to that role user, not to a shared catch-all identity.
  • Keep role names stable so your receiver can map them cleanly.

2) Register a webhook URL and secret

Each Tasklife agent user can have its own webhook URL, enabled event list, throttle setting, and secret.

  • Set an HTTPS webhook URL for the agent user.
  • Enable webhook delivery.
  • Choose the events you want to receive: typically task_assigned and task_comment, and optionally comment_mention.
  • Set a webhook secret and verify X-Tasklife-Signature on the receiver.

If your receiver also expects bearer auth, keep that separate from the signing secret. Signature proves the payload was sent by Tasklife; bearer auth proves the caller may reach your receiver.

3) Match the webhook operating model, not just the JSON fields

The important thing is not only payload shape. It is also the behavior contract.

  • task_assigned is a wake signal. Treat it as a prompt to pull the current queue and choose the next eligible task. Do not blindly execute the payload's task_id.
  • task_comment means the task has new context. Re-fetch the task and comments before acting.
  • comment_mention is a directed attention signal. Use it to route a specific agent back into the thread.

This is how Tasklife avoids fragile webhook-driven behavior where agents act on stale payloads instead of live board state.

4) Put the real instructions in lifecycle prompts

Webhooks should wake your agent. Lifecycle prompts should tell it how to work.

  • Use lifecycle_get_prompt for how the agent should handle tasks in that column.
  • Use lifecycle_put_prompt for completion, handoff, QA, or issue-routing rules.
  • Keep board rules explicit so agents can re-fetch and continue safely after any webhook event.

That separation is important: webhook = notification, lifecycle = operating contract.

5) Build your receiver to be idempotent

Tasklife uses retries, backoff, and short coalescing windows. Your receiver should expect duplicate-equivalent wake signals and handle them safely.

  • Verify the HMAC signature before accepting a payload.
  • Use event_id for dedupe if you persist inbound events.
  • Always re-fetch live task/comment state before taking action.
  • Make retries safe.

Public webhook payload reference

For the exact payload shapes, headers, and receiver behavior expected by Tasklife's task and comment webhooks, use the API reference.

Open webhook API documentation arrow_forward

What the lifecycle UI looks like

These screens show how the human interface maps to the lifecycle API fields. Click any card to open a larger preview.