Guide for agents

How a Claude Code session (the project's agent) works in a project that uses warden: the rules, the loop, and what to do when warden says no.

The short form ships with the plugin as the /warden:guide skill, so the project's agent can load it at any time. This page is the long form; on a machine with warden installed it is usually at ~/.claude/plugins/marketplaces/warden-marketplace/docs/for-agents.md.

The short version#

• Warden decides the steps. You ask with warden next, do the step, and hand in with warden done.
• Warden runs the checks and the code review itself. Your word that "tests pass" counts for nothing.
• A person approves, rejects, retries and resets. You tell the user what to type.
• When warden refuses something, it says why in a line that starts with warden:. Fix the cause. Do not look for a way around it.

Golden rules#

The loop#

flowchart TD
    next["warden next"] --> s{status}
    s -->|agent| work["Do the step"] --> done["warden done<br/>--json '...'"]
    done -->|"accepted: false"| fix["Fix each line of errors"] --> done
    done -->|accepted| next
    s -->|running_gate| wait["warden wait<br/>(Bash timeout 600000)"] --> s
    s -->|"waiting or blocked"| tell["Tell the user the message<br/>and end your turn"]
    s -->|"shipped or done"| over(["Run is over"])

1. Run warden next (with the task id when you are not in its worktree: warden next <task>).

2. Read the JSON it prints:

   Field	What it holds
   status	agent, running_gate, waiting, blocked, shipped, done or archived
   step	id, type, index, total, title; null once the run is over
   message	One or more lines for you, for example APP-12: implement (2/5). Back from check: CODE.
   instructions	What the step must achieve, the project rules, what to read, and earlier outputs
   output	schema (the TypeScript type to hand in) and example
   context	taskPath, and when they apply planPath, routeBack, fix, ship, waiting

3. Go by status:

   Status	Do this
   agent	Do the step as instructions says, then hand in.
   running_gate	Run warden wait with a Bash timeout of 600000. It waits up to 540 seconds. Repeat until the status changes.
   waiting	Tell the user the message and end your turn.
   blocked	Tell the user the message and end your turn.
   shipped, done, archived	Tell the user the run is over.

The Stop hook keeps your turn going while the run needs you. If it says <task> is at <step> and needs you, run warden next (or warden wait while a gate runs).

Starting a run#

Usually the user starts with /warden:compose <what to do> or /warden:compose <ticket id>, or the /warden:work skill starts one. Every run starts from a ticket. When you must start it yourself:

1. Run warden next. If it says there is no active run here and lists your task among the live runs, run cd <its worktree> as its own command, then warden next. Skip the rest of this list.

2. The task id is the ticket id and must match taskIdPattern in .warden/warden.json. If the user gave only text, create the ticket as /warden:compose says ("No task id"): the tool picks the id. Without a tickets role, warden start refuses: tell the user to add a ticket tool (/warden:tools).

3. Pick the template as /warden:compose does: feature for a new feature, schema or API change, many files, new UI, an auth entry point, or no label; bugfix for a bug in existing code; do for docs, config only, a typo or a single-file obvious edit; chore for a small change that must be merged, such as a chore ticket.

4. Run this, with a Bash timeout of 600000 (start reads the ticket and runs the project setup):

   bash

   warden start APP-12 --template feature --worktree

5. Run cd <worktree> as its own command, then warden next.

What each step asks of you#

Handing in output#

One command, the JSON on one line in single quotes:

warden done --json '{"summary":"Apply tax once","filesChanged":["src/cart.ts","tests/cart.test.ts"],"testsAdded":["tests/cart.test.ts"]}'

• Write a single quote inside the JSON as \u0027.
• warden done --file <path> also works, but --json keeps it to one simple command.
• warden done returns at once. It prints {"accepted", "errors", "next"}, where next is the same shape as warden next. Exit 0 when accepted, 1 when not, 4 while engine work is running.
• For implement, filesChanged is exactly what git -C <worktree> diff --name-only <step start> HEAD prints. The step start SHA is in the instructions (Step start: <sha>).

Shapes for the common steps (the full schema is always in output.schema):

{"summary":"...","filesChanged":["src/a.ts"],"testsAdded":["tests/a.test.ts"]}

{"summary":"...","filesChanged":["src/a.ts"],"testsAdded":[],"testsReason":"config only, no behaviour to test"}

{"pr":"https://example.com/pr/12","merged":false,"mergeCommit":null,"description":"Fix double tax."}

When you need the user#

At an agent step, ask through warden so the run waits and your turn may end:

warden ask "Should the export include archived rows?"

From outside the run's worktree, pass the task id: warden ask APP-12 "<question>". Show the user the question and end your turn. Their next message is the answer. Then run warden next and go on with the step.

• The question is 1 to 500 characters.
• warden ask works only at an agent step with no engine work running.
• A subagent cannot ask. A ticket agent replies ASK <Task>: <question> to its caller instead.

Blocked and waiting runs#

Tell the user the message and end your turn. They type one of these in the chat.

While a run is blocked at a check, review or approve step, your edits in the ticket worktree are refused (<type> step does not change code). So the person fixes the cause in their own editor or terminal, commits in the worktree, and then types retry. If the user asks you to fix it, explain this. You can still read files and tell them what to change.

With several live runs, the user adds the task id: approve APP-12, retry APP-12, reject APP-12: <why>, or APP-12: <answer>. See Blocked and waiting runs.

Common refusals and the fix#

From warden done#

From the hooks#

Each hook refusal starts with warden:.

From other commands#

More in Troubleshooting. Exit codes are in Exit codes.

A refusal that matches no row#

1. Read the whole message: most refusals name the fix or the command to run.
2. Run warden <command> --help and check your arguments.
3. Do not try another way around the refusal (a different tool, a shell trick, editing state files).
4. If the fix needs a person (approve, retry, reset, a locked file), tell the user what to type and end your turn.
5. If warden itself looks wrong or unclear, file it with /warden:report, with the exact message.

Session start lines#

At the start of a session, warden adds lines that begin with warden:. Act on them like this:

Reporting a warden problem#

When warden itself behaves against its own instructions (not when your code fails a check), send a report:

warden report --kind bug --title "warden wait never returns after review" --body "What happened: ... Expected: ... Steps: ... Evidence: <exact output>"

• Kind is bug or enhancement. The body is one argument; for a long body use --file <path>.
• No repository names, links, secrets, credentials or customer data.
• It prints {"id": "R-xxxx-NNNN", "status": "sent"}. Tell the user the id.
• The row goes to .warden/reports.md in the main checkout. Commit it there only when the main checkout is on the main branch and nothing else is staged: git -C <main> commit -m "chore: warden report <id>" -- .warden/reports.md. Never on a task branch. Do not push unless the user asks.

When a report needs more information, session start shows the question. Answer it from the project's code, config and logs, in one argument:

warden report reply R-eb85-0001 --body "<answer>"

See Reports.

Commands you run, and commands you never run#

See also#

• How warden works
• Gates and self-healing
• Blocked and waiting runs
• CLI reference
• Hooks
• Skills
• Troubleshooting