Warden documentation
On this page
Everything you need to install warden, run tasks with it, and look up how each part behaves.
Who each section is for#
| Section | For | What it holds |
|---|---|---|
| Getting started | Everyone new to warden | Install, set up a project, run a first task, upgrade |
| Concepts | Engineers and team leads | How warden thinks: runs, steps, gates, state, reports |
| Guides | Engineers and team leads | Step-by-step jobs: compose a workflow, write a tool, run an epic |
| Lead overview | Team leads | See every task with its time, tokens and estimated cost, and add them up |
| Reference | Anyone looking up a detail | Every command, file, setting, skill, hook and exit code |
| For agents | AI agents (Claude Code sessions) in your project | The rules and the loop, in one compact page |
| Help | Anyone stuck | Symptom to fix tables and common questions |
| Maintainers | People who work on warden itself | Triage, releases, contributing |
A few words used everywhere are in the Glossary at the end of this page.
Getting started#
- Installation: prerequisites, personal and team install, verify, uninstall.
- Quick start: set up your project with
/warden:init, run a first small task, then a feature from plan to ship. - Upgrading: how new versions arrive and how
/warden:upgradeapplies them to your project.
Concepts#
- How warden works: runs, steps, the engine, the
warden next/warden doneloop, and the hooks that keep it honest. - Workflows: the templates
do,feature,bugfixandchore, the step types, and custom flows. - Gates and self-healing: the check gate, proofs on the commit, triage, the fixer, the review gate and leftovers.
- State and history:
.warden/stateversus.warden/history, worktrees, what is committed, time and tokens per task. - Reports: telling the warden maintainers about a problem, report statuses, answering their questions.
- Checks and retro: periodic checks, which run by themselves and which are offered, and the retro.
- Tools and roles: your project's own tools in
.warden/tools/and thetickets,graphandprroles. - Orchestration: epics, the ticket graph, waves, ticket agents and merge order.
Guides#
- Compose a workflow
- Write a tool
- Write a ticket tool
- Orchestrate an epic
- Lead overview: the warden site
- Blocked and waiting runs
- Team setup
Reference#
- CLI: every
wardencommand and flag, its output and who runs it. - Exit codes
- Project files: every file and folder in
.warden/and which are committed. - steps.json: every field, its default and its rules.
- Flow files: the flow JSON format and the lint rules.
- Skills: every
/warden:*skill. - Hooks: what each hook allows, blocks and says.
- Environment: environment variables and the data folder.
For agents#
- Guide for agents: the golden rules, the loop, how to hand in output, what to do when blocked or waiting, and the commands never to run.
- The
/warden:guideskill ships the short form inside the plugin. The project's agent loads it by itself when it is unsure or refused. See Skills.
Help#
Maintainers#
Design notes and build specs from earlier versions are kept in internal/. They are not user docs and may be out of date; the code wins.
Glossary#
| Word | Meaning | More |
|---|---|---|
| Your project | The repository where you installed warden. | Quick start |
| The project's agent | The Claude Code session that works in your project. | For agents |
| Main checkout | The folder where you cloned the repo. Live state always lives here, even when a task runs in a worktree. | State and history |
| Worktree | A second checkout of the repo, with its own branch. Each task gets one, in <repo>/.worktrees/<task> (gitignored). | State and history |
| Task id | The id of a task, for example APP-12. It must match taskIdPattern in .warden/warden.json. | Project files |
| Run | One task going through its steps, from warden start to shipped or done. | How warden works |
| Step | One part of a run, such as plan, implement, check or ship. Its type decides who does it and which files it may change. | Workflows |
| Flow | The list of steps a run goes through. Also called a workflow. | Workflows |
| Template | A ready-made flow: do, feature, bugfix or chore. | Workflows |
| Engine | The part of warden that moves a run from step to step and checks every hand-in. | How warden works |
| Engine worker | The background process that runs the gates (warden gate <task>). | How warden works |
| Hand-in | The JSON output an agent gives with warden done at the end of a step. | For agents |
| Gate | A step that warden runs itself (check and review), so the agent cannot fake it. | Gates and self-healing |
| Proof | A record that a gate passed on one exact commit (its git SHA). A later commit or edit makes it stale. | Gates and self-healing |
| Stale proof | A proof that no longer covers HEAD, because the code changed after the gate. The gates then run again. | Gates and self-healing |
| Triage | Sorting a failed check by fault before anything is fixed. | Gates and self-healing |
| Verdict | The result of triage: CODE (the change broke it), OPS (the setup broke it) or UNCLEAR. | Gates and self-healing |
| Route back | The engine sends the run back to the latest implement step, with the reason. | Workflows |
| Triage rule | A saved pattern in .warden/triage-rules.json that gives a known failure its verdict at once. | Gates and self-healing |
| Fixer | The warden:fixer agent. It fixes a failure that is not (only) the change, on its own branch. | Gates and self-healing |
| Fix note | The fixer's write-up of a fix, in .warden/fixes/. | Project files |
| Finding | One problem the reviewer found: blocking or minor. | Gates and self-healing |
| Leftovers | Blocking findings still open after the last review round. The ship step lists them in the pull request description. | Gates and self-healing |
| Waiting | A run that needs a person's decision or answer. | Blocked and waiting runs |
| Blocked | A run that hit something a person must fix, then retry. | Blocked and waiting runs |
| Run record | The snapshot of a run in .warden/history/<task>/, committed at the ship step. | State and history |
| Gate files | Files no step may change: steps.json, flows/, warden.json, triage-rules.json, state/, history/ under .warden/. | Workflows |
| Locked config | Config files nobody may edit while any run is live: steps.json, flows/, warden.json, triage-rules.json, tools/roles.json under .warden/. | Workflows |
| Tool, role | A tool is a command your project keeps in .warden/tools/. A role (tickets, graph, pr) tells warden which tool to use for a job. | Tools and roles |
| Check (periodic) | A recurring job in .warden/checks/, such as the retro. Not the same as a check step. | Checks and retro |
| Retro | A look back at recent work, offered every 2 days. | Checks and retro |
| Report | A bug report or idea about warden, sent to the warden maintainers. | Reports |
| Epic, wave, ticket agent | An epic is a parent ticket. A wave is a group of its tickets that can run now. A ticket agent drives one ticket's run. | Orchestration |