Answer a setup task

A setup task is the platform asking a person for something it cannot invent: a value it does not hold, or a decision the work never settled. It is always a person’s to do, so an agent cannot be assigned one and bulk assignment skips them.

Where one comes from

Three places, and they all end in the same form:

An agent mid-run that needs a credential, an environment value, or an answer the task never gave it.
A question agreed in a huddle, which becomes a setup task when that huddle’s tasks are merged.
A connection a task needs, where the work reads a service nobody has connected.

What one can ask for

It asks for	The form shows	Example
A connection	A field for a credential, masked as you type	The analytics account the task reads
A secret value	A secret field	The staging key for the payments sandbox
A configuration value	A plain text field	The percentage a new feature rolls out to
A decision	Two to twelve named options, pick one	Ship behind a flag, or ship it on
A confirmation	A checkbox you tick and Confirm, saying you did something outside CommandChain	Installing a toolchain

Where your answer goes

Answer	Lands
A connection	Your workspace’s connected accounts, used by agents and never shown back
A secret value	The project environment’s write-only storage, released one attempt at a time
A configuration value	The project environment as a plain variable, readable afterwards
A decision, or any question with no value to store	Recorded on the waiting task, under Human answers in the spec the next run reads

An answer recorded on the task never rewrites its description: it sits beside the question, so the next run reads both. When several tasks waited on the same question, each gets the answer, so none is released without it.

Why a plain value can still be stored as a secret

An agent says whether a value is sensitive, and CommandChain does not take its word. When the name reads like the name of a credential, the field is a secret field whatever the agent asked for, and the form says so:

You asked for this as a plain value. Because the name contains SECRET, it is stored in the secret store.

The override is recorded on the task, and it goes one way only: nothing turns a secret back into a readable plain value.

The explanation at the top is the agent’s

Where an agent raised the task, the paragraph saying what it needs and why was written by that agent, and the form labels it Written by the agent’s name, or by an agent where the name is missing. Read it as a colleague’s request rather than product copy, and check it before handing anything over.

Never type a secret into a plain answer

A plain answer is prose the next run reads, so a credential typed into one becomes a credential in a prompt. The form turns such an answer away:

This looks like a secret. Ask for it on the setup form as a secret field instead of typing it into a plain answer.

A refused answer writes nothing, and the field stays open to submit again. Writing about keys and tokens is fine; only the value is turned away.

What happens to the run that is waiting

A run that raises a setup task does not sit and wait, because you may take a day.

It pushes everything written so far to the task’s branch, so nothing is lost.
It stops as inconclusive, recorded as waiting on setup. No review runs on work the agent has called unfinished, and the runner is free at once.
The task moves to blocked and names the setup task as what it is waiting on.

Completing it clears the block and dispatches the work again, carrying on from the branch the run pushed rather than starting over.

Install a toolchain

When no connected runner has a language a task needs, one install task per language goes to whoever approved the runner, else the task creator, the project owner, then the workspace’s first member. It carries commands for macOS, Debian or Ubuntu, and Fedora or RHEL.

Run them on a self-hosted runner’s machine, then open the runner with commandchain-runner and press r to check again: waiting tasks start on their own and the install task completes itself. Ticking the box and pressing Confirm also restarts them.

The install task is for self-hosted runners only: a managed run already has a fixed set of toolchains, and there is no managed machine to install on. If you use only managed runs and a task needs a language outside that set, install a self-hosted runner on a machine that has it, and the waiting task starts once that runner connects and reports it.

Next steps

Set environment variables and secrets: where a secret value actually lives.
Answer an assist task: the other thing an agent raises when it cannot go on alone.
Read a run: what the resumed run has to get through before it can finish.