Checks and retro

Periodic checks are small jobs that come due every few days; the retro is a built-in one that looks back at recent work.

These are not the check step of a run (see Gates and self-healing). Periodic checks run outside any task, in the main checkout.

A check file#

Each check is one Markdown file, .warden/checks/<name>.md, committed with the project. The name is lowercase letters, digits and dashes. The file starts with a frontmatter block (key: value lines between two --- lines), then text.

A command check runs a shell command:

---
every: 7d
kind: command
run: bun run audit
auto: true
timeoutSec: 120
---
# Dependency audit

Checks the dependencies for known problems.

An agent check gives the project's agent a job; its text is the instructions:

---
every: 14d
kind: agent
last: never
---
# Dead code sweep

List exported functions that nothing imports. Show the list to the user and ask before you remove anything.

A check is due when it never ran, or when every days have passed since its last run. A file with a bad key or value shows up in warden checks with an error and is never due.

Auto and offered checks#

At session start, warden looks at the due checks:

• Auto command checks (auto: true) start by themselves in the background, without a word. They are skipped while a live run uses the main checkout as its worktree.
• All other due checks are offered: session start adds the line warden: checks due: <name> (last <date>), .... The project's agent offers them in one short line when your current request is done, and starts one only if you say yes.
• A failed auto check gets its own line, warden: auto checks failed on their last run: ..., so the agent can tell you.

Running checks#

warden checks                 # every check: name, kind, every, last, due, auto, running, lastResult
warden checks run <name>      # run one now
warden checks done <name>     # mark an agent check done (today, or --date YYYY-MM-DD; optional --note "<one line>")

• warden checks run on a command check runs the command in the main checkout and prints passed, exit, durationMs and the log path. --background starts it detached and returns at once. It refuses while a live run uses the main checkout, or while the same check is already running (exit code 4).
• warden checks run on an agent check only prints its instructions and the warden checks done <name> command. The agent does the work, then marks it done.
• warden checks done is only for agent checks; command checks are marked by their own run.

Results never change the check file, so running a check never leaves the project dirty. They are kept in .warden/state/_checks/<name>.json (the last 50), with the log in <name>.log.

Built-in checks#

/warden:init writes two check files. You can change their frontmatter like any other check.

If .warden/checks/retro.md is missing, warden still lists a retro check with these defaults.

The retro#

The retro looks back at the work since the last retro and turns friction into fixes. It runs only when you ask for it, or say yes when it is offered.

1. The agent collects what happened: warden status --all, the run records in .warden/history/*/summary.json, the live state of runs without a ship step, the fix notes in .warden/fixes/, and the current conversation.
2. It writes two parts: Friction (what went wrong or took too long, each item concrete) and Routing (where each finding goes).
3. It shows you the retro and waits for your OK. It writes nothing before that.
4. It saves .warden/retros/<YYYY-MM-DD>.md in the main checkout (a second retro on the same day is added to the same file), makes the routed changes you agreed to, and updates each folder's INDEX.md.
5. It runs warden checks done retro (which needs the retro file for that date), then warden report --status --write.
6. It commits the files on the main checkout, only when it is on the main branch. It never pushes unless you ask.

Where findings go#

warden retro --done [--date YYYY-MM-DD] is an older alias of warden checks done retro.

See also#

• Reports
• Tools and roles
• Project files
• Skills reference
• CLI reference