Project files reference

Every file and folder warden reads or writes in your project, what each is for, and which ones you commit.

This page is also the map of the .warden/ folder. Each doc folder has one job, listed below.

The .warden/ layout#

.warden/
  warden.json            project id, task id format, site port, warden version   (committed)
  steps.json             setup, checks, review, triage, fixer scope               (committed)
  triage-rules.json      known failure patterns, added by the fixer               (committed)
  reports.md             table of reports sent to the warden maintainers          (committed)
  tools/                 the project's own tools and their roles                  (committed)
  flows/                 saved flows                                              (committed)
  context/               facts about the project                                  (committed)
  rules/                 rules every agent step must follow                       (committed)
  decisions/             choices that were made                                   (committed)
  knowledge/             facts learned while working on the code                  (committed)
  checks/                periodic checks                                          (committed)
  retros/                retro notes                                              (committed)
  fixes/                 notes from the fixer                                     (committed)
  history/<task>/        the run record of each shipped task                      (committed)
  state/                 live run state                                           (gitignored)

Each doc folder (context, rules, decisions, knowledge, checks, retros, fixes, flows) has an INDEX.md with one line per file.

Files at a glance#

"Locked while a run is live" means the hooks refuse edits to the file while any run is active, waiting or blocked. See hooks.

.warden/warden.json#

{ "schema": 1, "wardenVersion": "0.6.1", "projectId": "pg", "taskIdPattern": "^PG-\\d{3}$", "sitePort": 4400 }

site.thresholds (every key optional; a bad value falls back to its default and shows under Project health):

Every value but slowFactor is an integer of at least 1. See lead overview.

.warden/steps.json#

See the steps.json reference.

.warden/triage-rules.json#

Known failure patterns. A rule only labels a failure; it never decides the verdict. The fixer adds a rule with each fix, and the engine reads the rules from the main branch only.

{ "schema": 1, "rules": [
  { "id": "TR-0001", "pattern": "^error: PORT is not set$", "flags": "", "verdict": "OPS",
    "fixNote": ".warden/fixes/2026-10-01-PG-012.md", "task": "PG-012", "addedAt": "2026-10-01" } ] }

A new rule must be narrow: it must match a line of the failing log and no line of any log from a command that passed in the same run.

.warden/reports.md#

A Markdown table of the reports this project sent to the warden maintainers:

| ID | Title | Status | Fixed in |
|---|---|---|---|
| R-eb85-0001 | warden wait times out on a slow review | fixed | 0.6.1 |

warden report adds a row. warden report --status --write brings the rows up to date. Session start never changes this file; it only tells the agent when a status changed. The report records themselves live in the data folder (see environment). It is always the main checkout's copy that changes, also when the command runs in a task worktree.

.warden/tools/#

The project's own tools. See tools and roles and write a tool.

Role and tool names match ^[a-z][a-z0-9-]{0,40}$. warden uses the roles tickets, graph and pr.

.warden/flows/#

Saved flows, <name>.json, plus INDEX.md with lines - <name>.json: <description>. Written by warden flow save. See flow files.

Doc folders#

Each folder has a single purpose. Keep each file under 200 lines and give it a line in the folder's INDEX.md. warden docs check (and the built-in warden-docs check, once a day) checks this for context, rules, decisions, knowledge, checks and retros.

The site (warden site) shows the files of context, rules, decisions, knowledge, checks, retros and fixes.

An INDEX.md line is a list item. Either a link, - [Title](file.md), or a name and a description, - file.md: description.

Fix note format#

The fixer writes it, and warden checks these headings exactly:

# Fix 2026-10-01 PG-012
## Symptom
## Root cause
## Fix
## Test
## How triage should classify this next time

.warden/checks/#

One Markdown file per periodic check, <name>.md, with name matching ^[a-z][a-z0-9-]{0,40}$. The file starts with a frontmatter block between two --- lines.

---
every: 1d
kind: command
run: warden docs check
auto: true
timeoutSec: 60
---
# Warden docs check

What the check is for, and what to do when it fails.

Unknown or repeated keys make the file invalid. For an agent check, the text after the frontmatter (up to a ## Results heading, if any) is what warden checks run <name> prints as instructions.

warden init --write adds two built-in checks:

When retro.md is missing, warden still lists a retro check built from the old lastRetro field.

.warden/history/<task>/#

The run record, written by the engine when the run enters its ship step, into the task worktree. The ship step commits it with the change, so it lands on the main branch with the PR. A run without a ship step (for example do) has no history folder.

Logs, raw reviewer output and the steps.json copy are not copied. The engine rewrites the folder each time the run enters the ship step again.

summary.json:

{
  schema: 1; task; flow; status: "shipping";
  startedAt; endedAt; durationMs;
  steps: { id, type, startedAt, endedAt, durationMs, attempts,
           tokens: { input, output, cacheRead, cacheWrite }, costUsd }[];
  rounds: { review, fixer, checkRuns, codeStrikesTotal };
  verdicts: { verdict: "CODE" | "OPS" | "UNCLEAR"; rule: string | null; at }[];
  findings: { blocking, minor, dropped, leftovers };
  tokens: { input, output, cacheRead, cacheWrite }; costUsd;   // costUsd is an estimate
  author: { name, email }; commit; pr: null; branch;
}

Tokens come from the transcripts of the sessions and subagents linked to the task. The reviewer's tokens and cost are added to the review step.

.warden/state/#

Live state. It is gitignored and lives in the main checkout only, even for runs in other worktrees. Never edit it by hand; use warden reset to remove a run.

.warden/state/
  <task>/
    run.json               the run: status, current step, counters, proofs, waiting reason
    flow.json              the flow copy
    steps.json             the steps.json copy from the main branch
    task.md                the task text
    plan.md                the accepted plan
    events.jsonl           one event per line
    sessions.jsonl         the sessions and subagents that worked on the task
    gate.log               output of the engine worker
    setup-<i>.log          setup at start
    retry-setup-<i>.log    setup after a retry merged the main branch
    checks/<n>/<name>.log  check command logs, one folder per check run
    triage/<n>.json        triage reports; triage/<n>/ holds their logs
    review/<round>-<try>.json, .raw.txt   review rounds and the reviewer's raw output
    review/leftover.md     findings left after the last review round
    outputs/<seq>-<step>.json             every hand-in, accepted or not
    fix/<n>.json, fix/<n>-repair-<i>.log  fixer outputs and repair logs
    .lock                  the task lock
  _sessions/               one record per Claude Code session (and per subagent)
  _checks/<name>.json      periodic check results; <name>.log and <name>.lock while running
  _orchestrate/<epic>.json the cached orchestrate plan
  _reports.json            report statuses already told at session start

Folder names that start with _ are not tasks.

run.json fields you will meet#

Event types#

Events in events.jsonl have {seq, ts, task, type, step?, data?}. Types:

run.started, step.started, step.ended, output.accepted, output.rejected, gate.started, gate.command, gate.passed, gate.failed, gate.restarted, gate.discarded, triage.verdict, fix.started, fix.result, fix.landed, review.round, route.back, approve.waiting, approve.granted, approve.rejected, approve.skipped, run.blocked, run.retry, retry.merged-main, history.written, run.shipped, run.done, run.archived (0.9.4, with the reason), session.linked, stop.blocked, hook.denied, git.fetch-failed, proof.stale, ticket.status, question.asked, question.answered.

Files outside .warden/#

Task branches default to the task id in lower case. Fix branches are warden-fix/<task>-<n>.

What to commit#

Commit everything under .warden/ except state/, plus scripts/warden-setup.sh, .gitignore, and .claude/settings.json when you use the team install. warden start reads .warden/ from the main branch, so push it there before the first run.

See also#

• State and history
• steps.json
• Flow files
• Environment
• Checks and retro
• Tools and roles