Reference / Commands
solomonar task
Plan, register, inspect, move, block, hand off, and complete Solomonar tasks with the solomonar task commands, with real examples of each.
On this page
The task commands read and write the task registry, state.json on the branch refs/heads/workflow-state. They are the only way the registry is written: each write is validated against the record and Git, and becomes one registry commit. They need a project prepared with init.
The examples on this page come from one run of the current build in the fictional ledger project. They follow task W-001 from plan to done. Paths are shortened to /work/ledger; the SHAs and timestamps are those the run produced.
Conventions
Task IDs have the form W-NNN. Every writing task command accepts --json and --dry-run, and a successful write is one commit on the registry branch. When the project has a remote, the CLI pushes that commit and prints pushed origin/workflow-state; without one it warns that the registry stays local.
| Value | Format |
|---|---|
--as <owner> |
Acting owner, an agent ID such as orchestrator-1. Defaults to SOLOMONAR_OWNER; a command that needs an owner and has neither fails with owner_required. |
--next <actor>:<action> |
Next action. The actor is user, the owner, or an active agent ID; the action is 1 to 120 characters. |
<full-sha> |
A full 40-character hexadecimal commit SHA; short SHAs are rejected. |
The task state page explains the statuses and stages.
solomonar task plan
Adds a planned task under the next free W-NNN. A planned task has no owner, stage, or branch yet.
When to use it
To queue work you want done later, or to record the order of tasks with --depends-on before any orchestrator picks them up.
Who runs it
You. An orchestrator does not plan tasks; it claims one with task register.
solomonar task plan --title <title> [--depends-on <ID>]... [--related <ID>] [--json] [--dry-run]
Flags
| Flag | Meaning |
|---|---|
--title |
Required. The task title; it must not be blank. |
--depends-on |
A task this one depends on; repeatable. It must exist. |
--related |
One related task, such as the done task this one follows up. It must exist. |
Example
solomonar task plan --title "Add a shared expense"
solomonar task plan --title "List expenses by month" --depends-on W-001
Planned W-001: Add a shared expense
state(W-001): planned, plan "Add a shared expense"
registry @ abbc81a0e1f080e6e8bffbc456851c5859cdac95 · pushed origin/workflow-state
With --json --dry-run, the command runs every check and reports the record it would write:
solomonar task plan --title "Export to CSV" --json --dry-run
{
"ok": true,
"command": "task plan",
"data": {
"id": "W-003",
"record": {
"title": "Export to CSV",
"status": "planned",
"updated_at": "2026-10-22T17:21:04Z"
},
"dry_run": true
},
"warnings": []
}
solomonar task register
Reserves the next free W-NNN, or claims the planned <ID>, for one orchestrator. The task starts reserved at stage setup, on branch feature/<ID>. This is the registration barrier: the next task may start only after the registration is confirmed.
When to use it
At the start of every task, before the branch and worktree exist.
Who runs it
The orchestrator agent, when you ask a session for an outcome. You see its result as Registration confirmed.
solomonar task register [<ID>] --title <title> --owner <owner> [--depends-on <ID>]... [--related <ID>]
[--next <actor>:<action>] [--json] [--dry-run]
Flags
| Flag | Meaning |
|---|---|
<ID> |
Optional. A planned task to claim; any other status is not_planned. |
--title |
Required. On a claim, a different title replaces the planned one with the warning title_changed. |
--owner |
Required. The orchestrator's agent ID. It must not own another reserved, running, blocked, or paused task (owner_in_use). |
--depends-on, --related |
As for task plan. On a claim, they replace the planned values when given. A dependency that is not done is the warning dependency_not_done. |
--next |
Initial next action; the actor is user or the owner. |
Example
Claim the planned W-001:
solomonar task register W-001 --title "Add a shared expense" --owner orchestrator-1
Registered W-001: Add a shared expense
status reserved / setup
owner orchestrator-1
branch feature/W-001 (create it now)
next orchestrator-1: Create feature/W-001 and its worktree
state(W-001): reserved/setup, registered by orchestrator-1
registry @ b0260cd4435162e74248f15f290c90fb46b609e8 · pushed origin/workflow-state
Registration confirmed. The next task may start.
Create the worktree:
git worktree add -b feature/W-001 ../ledger-worktrees/W-001 main
solomonar task show
Read-only. Without an ID it prints every task sorted by ID, with its status, stage, owner, and next action, and the registry commit. With an ID it prints the stored record exactly as JSON.
When to use it
To see at a glance what is running, blocked, or waiting on you, or to read one record as the agents see it.
Who runs it
You, most often. Agents read it too when they resume.
solomonar task show [<ID>] [--json]
Example
The registry overview while W-001 is registered:
solomonar task show
ID STATUS STAGE OWNER NEXT
W-001 reserved setup orchestrator-1 orchestrator-1: Create feature/W-001 and its worktree
W-002 planned - - -
registry refs/heads/workflow-state @ a2b3473 · 2026-10-22T17:21:04Z
One record, while W-001 waits on a decision:
solomonar task show W-001
{
"title": "Add a shared expense",
"status": "blocked",
"stage": "implementation",
"owner": "orchestrator-1",
"branch": "feature/W-001",
"spec": "docs/work/W-001-add-shared-expense.md",
"active_agents": [
{
"id": "impl-1",
"role": "implementer"
}
],
"blockers": [
{
"id": "B-1",
"kind": "decision",
"summary": "Choose local storage for expenses",
"ref": "W-001/D-1"
}
],
"last_blocker": 1,
"next_action": {
"actor": "user",
"action": "Approve a storage option for W-001/D-1"
},
"updated_at": "2026-10-22T17:21:20Z"
}
solomonar task status
Read-only. It prints the stored record, the Git facts (branch, worktree, HEAD, dirty files, spec, merge state), the pull request and checks from gh when available, any drift between them, and the commands valid next. It exits 0 whatever the drift.
When to use it
To check that a task's record matches what Git shows, and when a session ended unexpectedly: the drift and the allowed commands tell the next session where to continue.
Who runs it
You and agents. An orchestrator runs it before resuming a task.
solomonar task status <ID> [--json] [--no-forge]
Flags
| Flag | Meaning |
|---|---|
--no-forge |
Skip gh. Unknown forge facts never count as passing. |
SOLOMONAR_OWNER, when set, lets the command report a task owned by another orchestrator as owned_by_other.
Example
After the pull request merged but before task done:
solomonar task status W-001 --no-forge
W-001 Add a shared expense
record
status running / integration owner orchestrator-2 tier 0
spec docs/work/W-001-add-shared-expense.md
revision c2eb0409c46f23bf8c89c856b1ac46f175f3bdf0
agents none
blockers none
next orchestrator-2: Merge after checks pass
pr 12
updated 2026-10-22T17:21:27Z (registry @ 627c4b8)
git
branch feature/W-001 @ e0e85c9cfb6b901e8ed34bffa04c37a5f9f34aa2
worktree /work/ledger-worktrees/W-001
HEAD e0e85c9c · 1 commit ahead of revision
dirty clean
spec present in worktree and at revision
merged yes, by e53d5697b950d3417a659fd9a6a23728d0c854be (merge commit on main)
spec_ref derived e0e85c9cfb6b901e8ed34bffa04c37a5f9f34aa2:docs/work/W-001-add-shared-expense.md (last spec(W-001) commit merged)
forge (gh)
pr unknown (--no-forge)
checks unknown
drift
head_ahead_of_revision HEAD is 1 commit past the recorded revision
merged_not_done feature/W-001 is merged into main but the record is not done
allowed next
solomonar task done W-001 --as orchestrator-2 --merge e53d5697b950d3417a659fd9a6a23728d0c854be --spec-ref <PR "Final specification" line> --summary <one sentence>
Here the drift is expected: the final spec commit follows the reviewed revision, and the merge is waiting for task done.
solomonar task move
Applies every given field flag as one validated update and one registry commit. At least one field flag is required. Only the owner may move a task. done and complete are written only by task done.
When to use it
At each step of a task: starting the specification, entering implementation with the recorded spec, recording the reviewed revision and tier, changing the delegated agents, recording the pull request, pausing, or cancelling.
Who runs it
The orchestrator that owns the task. You ask for a pause or a cancellation in the session; the orchestrator runs the command.
solomonar task move <ID> [--as <owner>]
[--status <reserved|running|blocked|paused|cancelled>] [--resume-cancelled]
[--stage <setup|specification|implementation|specialized_review|adversarial_review|integration>]
[--revision <full-sha>] [--spec <worktree-relative path>] [--tier <0|1|2>]
[--agent <id>:<role>]... | [--agent none]
[--pr <url|number>] [--next <actor>:<action>]
[--json] [--dry-run]
Flags
| Flag | Meaning |
|---|---|
--status |
New status. running leaves setup together with --stage specification; blocked needs an open blocker; paused and cancelled need --next. From blocked or paused, only the prior status or cancelled is allowed. |
--resume-cancelled |
Required to return a cancelled task to its prior status, on the user's explicit instruction. |
--stage |
New stage. Forward moves follow the tier: tier 0 goes from implementation to integration, tier 1 adds specialized_review, tier 2 adds adversarial_review. Some backward moves are allowed for rework. A blocked or paused task keeps its stage. |
--revision |
The reviewed candidate commit on feature/<ID>. Accepted when the current or resulting stage is implementation or integration. |
--spec |
The work specification, a clean path relative to the worktree. Accepted from specification on; entering implementation needs it. |
--tier |
Review tier 0, 1, or 2. Stages after implementation need it, passed with --revision. |
--agent |
An active delegated agent as <id>:<role>, such as impl-1:implementer; repeatable, replacing the list. --agent none clears it. The role is a core delegated role or an installed agent extension, never orchestrator or a draft. |
--pr |
The pull request, as a positive number or an https:// URL. Accepted in integration. |
--next |
New next action. An agent added by --agent in the same command may be the actor. |
Example
Start the specification, then enter implementation with the committed work spec and a delegated implementer:
solomonar task move W-001 --as orchestrator-1 --status running --stage specification \
--next "orchestrator-1:Write the work spec"
solomonar task move W-001 --as orchestrator-1 --stage implementation \
--spec docs/work/W-001-add-shared-expense.md --agent impl-1:implementer \
--next "impl-1:Implement the add-expense flow"
W-001 reserved/setup → running/specification
next orchestrator-1: Write the work spec
state(W-001): running/specification, status running, stage specification, next orchestrator-1
registry @ f5feb47defc2ba481c5bfa5a5c5149ad592809c5 · pushed origin/workflow-state
W-001 running/specification → running/implementation
spec docs/work/W-001-add-shared-expense.md (found in /work/ledger-worktrees/W-001)
agents impl-1 implementer
next impl-1: Implement the add-expense flow
state(W-001): running/implementation, stage implementation, spec docs/work/W-001-add-shared-expense.md, agents impl-1, next impl-1
registry @ 92a4704fdf1d8fc2f06ac039ce85948eeecac8c2 · pushed origin/workflow-state
A move the record cannot support is rejected, exits 3, and writes nothing:
solomonar task move W-001 --as orchestrator-1 --stage integration
error: task move W-001 rejected (tier_required)
check: a stage after implementation needs a recorded tier
found: implementation -> integration
fix: triage the candidate and pass --revision <full-sha> --tier <0|1|2> with the stage move
nothing was written
With the reviewed revision and its tier, the same move succeeds:
solomonar task move W-001 --as orchestrator-1 --stage integration \
--revision c2eb0409c46f23bf8c89c856b1ac46f175f3bdf0 --tier 0 --agent none \
--next "orchestrator-1:Open the pull request"
W-001 running/implementation → running/integration
revision c2eb0409c46f23bf8c89c856b1ac46f175f3bdf0 (on feature/W-001)
tier 0: no review stages
agents none
next orchestrator-1: Open the pull request
state(W-001): running/integration, stage integration, revision c2eb040, tier 0, agents none, next orchestrator-1
registry @ b6a9d5b2dcb8b2ecdc60f056f5276024d31f8424 · pushed origin/workflow-state
solomonar task block
Adds an open blocker B-n to the task. --status and --next are shorthands for the same task move fields, so one blocking event is one registry commit.
When to use it
When part of the work cannot continue: a decision only you can make, a task it depends on, a failing check, or a broken environment.
Who runs it
The orchestrator that owns the task. For a decision, it then asks you in the session, quoting the decision ID.
solomonar task block <ID> --kind <decision|dependency|check|environment> --summary <text> [--ref <ref>]
[--next <actor>:<action>] [--status blocked] [--as <owner>] [--json] [--dry-run]
Flags
| Flag | Meaning |
|---|---|
--kind |
Required. decision, dependency, check, or environment. |
--summary |
Required. What blocks the task. |
--ref |
A reference for the blocker. Required with --kind decision, as <ID>/D-n. |
--status blocked |
Also set the status to blocked. |
--next |
Also set the next action, typically user:<decision to make>. |
Example
Stop for a storage decision:
solomonar task block W-001 --as orchestrator-1 --kind decision --ref W-001/D-1 \
--summary "Choose local storage for expenses" --status blocked \
--next "user:Approve a storage option for W-001/D-1"
W-001 running/implementation → blocked/implementation
blocker B-1 decision: Choose local storage for expenses (W-001/D-1)
next user: Approve a storage option for W-001/D-1
state(W-001): blocked/implementation, block B-1 decision
registry @ 823582e8c0085952f9fbf2777fb4bbb901dc0be6 · pushed origin/workflow-state
solomonar task unblock
Clears one open blocker, given by its ID such as B-1.
When to use it
When the blocking cause is resolved: you answered the decision, the dependency is done, or the check or environment works again.
Who runs it
The orchestrator that owns the task, after it receives your answer.
solomonar task unblock <ID> <blocker-id> [--status <prior status>] [--next <actor>:<action>]
[--as <owner>] [--json] [--dry-run]
Flags
| Flag | Meaning |
|---|---|
<blocker-id> |
Required. An open blocker of the task; anything else is blocker_not_found. |
--status |
The prior status to resume: reserved at stage setup, running at any later stage. Required when the last blocker of a blocked task is cleared. |
--next |
Also set the next action. |
Example
You approved SQLite for W-001/D-1:
solomonar task unblock W-001 B-1 --as orchestrator-1 --status running \
--next "impl-1:Implement the add-expense flow with SQLite"
W-001 blocked/implementation → running/implementation
cleared B-1 decision: Choose local storage for expenses
next impl-1: Implement the add-expense flow with SQLite
state(W-001): running/implementation, unblock B-1
registry @ 42d70e8472adf2b6e9999cfc381cd4393be5ca2d · pushed origin/workflow-state
solomonar task handoff
Transfers ownership to a new orchestrator. It takes no --as and ignores SOLOMONAR_OWNER; the previous owner must stop writing the record. Every status except planned and done accepts a handoff.
When to use it
When the session that owns a task is gone or must stop, and another session takes over the same task.
Who runs it
The new orchestrator, only on your explicit instruction. Agents never take over a task on their own.
solomonar task handoff <ID> --owner <new-owner> [--next <actor>:<action>] [--json] [--dry-run]
Flags
| Flag | Meaning |
|---|---|
--owner |
Required. The new owner's agent ID. It must differ from the current owner and must not own another active task. |
--next |
New next action. Without it, a next action of the previous owner moves to the new owner with the same text. |
Example
solomonar task handoff W-001 --owner orchestrator-2
W-001 owner orchestrator-1 → orchestrator-2 (running/integration)
next orchestrator-2: Open the pull request
state(W-001): running/integration, handoff orchestrator-1 -> orchestrator-2
registry @ c49649696f1b35ba10805498b2d9a7f5478246b5 · pushed origin/workflow-state
The previous owner must stop writing this record.
The new owner then records the pull request with task move:
solomonar task move W-001 --as orchestrator-2 --pr 12 --next "orchestrator-2:Merge after checks pass"
W-001 running/integration
next orchestrator-2: Merge after checks pass
pr 12
state(W-001): running/integration, next orchestrator-2, pr 12
registry @ 627c4b80a785ec70ef8cbc13a5e66da296566846 · pushed origin/workflow-state
solomonar task done
Completes a running task at stage integration with no open blocker, after its pull request merged. It verifies the facts with Git only, then replaces the record with the compact done record.
When to use it
Right after the pull request is merged with a merge commit. task status lists the exact command, with the merge commit filled in.
Who runs it
The orchestrator that owns the task. You read the result with task show.
solomonar task done <ID> --merge <full-sha> --spec-ref <full-sha>:<path> --summary <text>
[--as <owner>] [--json] [--dry-run]
Flags
| Flag | Meaning |
|---|---|
--merge |
Required. The merge commit: reachable from the local main branch, with two or more parents, and containing the recorded revision. A squash or rebase merge is rejected. |
--spec-ref |
Required. <full-sha>:<path> of the final specification: the last spec(<ID>): commit of the merged branch, with the path equal to the recorded spec. Copy it from the pull request's "Final specification" line. |
--summary |
Required. A one-line summary of 1 to 120 characters. |
Example
solomonar task done W-001 --as orchestrator-2 \
--merge e53d5697b950d3417a659fd9a6a23728d0c854be \
--spec-ref e0e85c9cfb6b901e8ed34bffa04c37a5f9f34aa2:docs/work/W-001-add-shared-expense.md \
--summary "Add and list shared expenses with SQLite storage"
Verified
merge e53d5697 is a merge commit reachable from main
revision c2eb0409 is contained in the merge
spec_ref resolves; e0e85c9c is the last spec(W-001) commit merged
W-001 running/integration → done/complete
state(W-001): done/complete, merged e53d569
registry @ db65aad2ac8ba02c6fc70c18baa99a94ada6684b · pushed origin/workflow-state
Compact record
{
"title": "Add a shared expense",
"status": "done",
"stage": "complete",
"pr": "12",
"summary": "Add and list shared expenses with SQLite storage",
"spec_ref": "e0e85c9cfb6b901e8ed34bffa04c37a5f9f34aa2:docs/work/W-001-add-shared-expense.md",
"merge_commit": "e53d5697b950d3417a659fd9a6a23728d0c854be",
"updated_at": "2026-10-22T17:21:33Z"
}
Next: delete the worktree only after confirming it holds no uncommitted or unmerged work:
git worktree remove ../ledger-worktrees/W-001
The registry overview now shows the summary in place of a next action:
ID STATUS STAGE OWNER NEXT
W-001 done complete - Add and list shared expenses with SQLite storage
W-002 planned - - -
registry refs/heads/workflow-state @ db65aad · 2026-10-22T17:21:33Z