Warden

Run Warden to analyze code changes before committing.

References

Read the relevant reference when the task requires deeper detail:

Running Warden

# Analyze uncommitted changes (uses warden.toml triggers)
warden

# Run a specific skill
warden --skill <skill-name>

# Analyze specific files
warden src/auth.ts src/database.ts

# Analyze changes from a git ref
warden main..HEAD
warden HEAD~3

# Auto-apply suggested fixes
warden --fix

# Fail on high-severity findings
warden --fail-on high

Set WARDEN_MODEL and the WARDEN-prefixed provider API key for that model before running.

Pre-Commit Workflow

After making code changes and before committing:

1. Run warden to analyze uncommitted changes 2. Review the findings 3. Fix issues Warden reports (or use warden --fix to auto-apply) 4. Commit the changes

Run Warden once to validate work. Do not loop re-running Warden on the same changes.

Reading Output

Severity levels:

• high - Must fix before merge
• medium - Worth reviewing
• low - Minor improvement

Exit codes: 0 = no findings at or above fail threshold. 1 = findings at or above fail threshold.

Verbosity: -v shows real-time findings. -vv shows debug info (tokens, latency). -q shows errors and summary only.

Commands

For full options and flags, read <skill-root>/references/cli-reference.md.

CLI Reference

Contents

• Usage
• Commands
• Targets
• Options
• Per-Command Options
• Severity Levels
• Exit Codes
• Examples

Usage

warden [command] [targets...] [options]

Commands

Targets

Ambiguous targets (no path separator, no extension) are resolved by checking if a file exists at the path. Use --git to force git ref interpretation.

Options

Per-Command Options

Init:

Add:

Sync:

Setup-app:

Severity Levels

Exit Codes

Examples

# Initialize
warden init

# Interactive skill selection
warden add
warden add security-review
warden add --list

# Remote skills
warden add --remote <org>/<repo> --skill <skill-name>
warden add --remote https://github.com/<org>/<repo> --skill <skill-name>
warden add --remote <org>/<repo>@<ref> --skill <skill-name>

# Run analysis
warden                                  # Skills from warden.toml
warden src/auth.ts                      # Specific file
warden src/auth.ts --skill <skill-name>
warden "src/**/*.ts"                    # Glob pattern
warden HEAD~3                           # Git changes
warden HEAD~3 --skill <skill-name>
warden main..HEAD                       # Branch diff

# Output control
warden --json
warden --fail-on high
warden -o results.jsonl

# Fix mode
warden --fix

# Cached skills only
warden --offline
warden sync                             # Update all unpinned remote skills

# GitHub App setup
warden setup-app
warden setup-app --org myorg

warden.toml Configuration Schema

Contents

• Top-Level Structure
• Defaults Section
• Skills Section
• Severity Values
• Built-in Skip Patterns
• Environment Variables

Top-Level Structure

version = 1                    # Required, must be 1

[defaults]                     # Optional, inherited by all skills
[defaults.agent]               # Optional, default analysis runtime settings
[defaults.auxiliary]           # Optional, default helper model settings
[defaults.synthesis]           # Optional, default synthesis model settings
[[skills]]                     # Required, array of skill configs

Defaults Section

[defaults]
runtime = "pi"                        # Default runtime
model = "openai/gpt-5.5"              # Legacy default analysis model
maxTurns = 50                         # Legacy default analysis turns
defaultBranch = "main"                # Base branch for comparisons
failOn = "high"                       # Exit 1 if findings >= this severity
reportOn = "medium"                   # Show findings >= this severity
maxFindings = 50                      # Max findings to report (0 = unlimited)
reportOnSuccess = false               # Post report even with no findings
ignorePaths = ["*.test.ts"]           # Exclude matching files

[defaults.ignore]
paths = ["**/fixtures/**", "!**/fixtures/regressions/**"] # Gitignore-style global ignore overrides

[defaults.scan]
maxFiles = 150                        # Max files analyzed after ignores
maxChangedLines = 10000               # Max changed lines analyzed after ignores
maxFileBytes = 1048576                # Max bytes for files whose contents may be read
maxFileLines = 3000                   # Max lines for files whose contents may be read

[defaults.agent]
model = "openai/gpt-5.5"              # Default repo-aware analysis model
maxTurns = 50                         # Max agentic turns per hunk
effort = "medium"                     # off | low | medium | high | xhigh

[defaults.auxiliary]
model = "anthropic/claude-haiku-4-5"  # Helper model for extraction and fix gates
maxRetries = 5                        # Retries for auxiliary structured calls

[defaults.synthesis]
model = "anthropic/claude-opus-4-5"   # Consolidation and generated-skill build model

[defaults.chunking]
enabled = true                 # Enable hunk-based chunking

[defaults.chunking.coalesce]
enabled = true                 # Merge nearby hunks
maxGapLines = 30               # Lines between hunks to merge
maxChunkSize = 8000            # Max chars per chunk

[[defaults.chunking.filePatterns]]
pattern = "*.config.*"         # Glob pattern
mode = "whole-file"            # per-hunk | whole-file | skip

[defaults.agent].effort controls repo-aware skill reasoning across runtimes. When omitted, Warden sends explicit high adaptive thinking to the Claude runtime; Pi uses its own default thinking level.

[defaults.synthesis].model falls back to [defaults.auxiliary].model when omitted. Legacy [defaults].model and [defaults].maxTurns are still supported as analysis fallbacks.

Skills Section

[[skills]]
name = "skill-name"            # Required, unique identifier
remote = "owner/repo@sha"      # Optional, fetch skill from GitHub repo
paths = ["src/**"]             # Include only matching files
ignorePaths = ["**/*.test.ts"] # Exclude matching files

# Optional overrides (inherit from defaults if not set)
model = "anthropic/claude-opus-4-5"
maxTurns = 100
failOn = "high"
reportOn = "medium"
maxFindings = 20
reportOnSuccess = true

[[skills.triggers]]
type = "pull_request"          # Required: pull_request | local | schedule
actions = ["opened", "synchronize"]  # Required for pull_request

# Schedule-specific (only for type = "schedule")
[[skills.triggers]]
type = "schedule"

[skills.triggers.schedule]
issueTitle = "Daily Security Review"   # GitHub issue title for tracking
createFixPR = true                     # Create PR with fixes
fixBranchPrefix = "security-fix"       # Branch name prefix

Trigger types:

• pull_request - Triggers on PR events
• local - Local CLI only (will not run in CI)
• schedule - Cron schedule (GitHub Action only)

All skills run locally regardless of trigger type. Skills with no triggers run everywhere (wildcard). Use type = "local" for skills that should only run locally.

Actions (for pull_request):

• opened, synchronize, reopened, closed

Severity Values

Used in failOn and reportOn:

• high - Must fix before merge
• medium - Worth reviewing
• low - Minor improvement
• off - Disable threshold

Built-in Skip Patterns

Skipped by default, with ! patterns in [defaults.ignore].paths available for re-inclusion:

• Package locks: pnpm-lock.yaml, package-lock.json, yarn.lock, Cargo.lock, etc.
• Minified, bundled, and source map files.
• Build/vendor/cache artifacts: dist/, build/, node_modules/, vendor/, .next/, coverage/, etc.
• Generated code paths and suffixes: *.generated.*, *.g.ts, *.pb.go, *_pb2.py, __generated__/, etc.
• Binary, media, archive, font, and bulky data files.

Environment Variables

Model Precedence (highest to lowest)

1. Skill-level model 2. [defaults.agent] model 3. [defaults] model (legacy fallback) 4. CLI --model flag 5. WARDEN_MODEL env var 6. SDK default

Configuration (warden.toml)

Contents

• Minimal Example
• Skill Configuration
• Common Patterns
• Model Lanes
• Model Precedence
• Environment Variables
• Troubleshooting

See config-schema.md for the complete schema reference.

Minimal Example

The name field references a skill you've created (via warden add) or defined in .agents/skills/<name>/SKILL.md. Use that same name everywhere — in config, CLI flags, and triggers.

version = 1

[defaults.agent]
model = "openai/gpt-5.5"
effort = "medium"

[[skills]]
name = "my-skill"           # matches .agents/skills/my-skill/SKILL.md
paths = ["src/**/*.ts"]

[[skills.triggers]]
type = "pull_request"
actions = ["opened", "synchronize"]

Skill Configuration

Skills define what to analyze and when. Each skill requires a name. Triggers are optional — skills with no triggers run everywhere (PR, local, schedule). All skills run locally regardless of trigger type.

[[skills]]
name = "my-skill"
paths = ["src/auth/**", "src/payments/**"]
failOn = "high"
reportOn = "medium"
maxFindings = 20

[[skills.triggers]]
type = "pull_request"
actions = ["opened", "synchronize"]

Trigger types: pull_request, local (local-only), schedule (CI-only)

Actions (pull_request): opened, synchronize, reopened, closed

Common Patterns

Strict checks on critical files:

[[skills]]
name = "my-skill"
model = "anthropic/claude-opus-4-5"
maxTurns = 100
paths = ["src/auth/**", "src/payments/**"]
failOn = "high"

[[skills.triggers]]
type = "pull_request"
actions = ["opened", "synchronize"]

Skip test files:

[[skills]]
name = "my-skill"
paths = ["src/**/*.ts"]
ignorePaths = ["**/*.test.ts", "**/*.spec.ts"]

Whole-file analysis for configs:

[[defaults.chunking.filePatterns]]
pattern = "*.config.*"
mode = "whole-file"

Model Lanes

Warden uses different model lanes for different kinds of work:

• Analysis: repo-aware skill execution uses [[skills]].model, then [defaults.agent].model, then legacy [defaults].model
• Auxiliary: structured helper calls use [defaults.auxiliary].model
• Synthesis: post-analysis consolidation and generated-skill builds use [defaults.synthesis].model

If [defaults.synthesis].model is omitted, synthesis falls back to [defaults.auxiliary].model.

[defaults.agent].effort optionally controls repo-aware skill reasoning across runtimes. Supported values are off, low, medium, high, and xhigh. When omitted, Warden sends explicit high adaptive thinking to the Claude runtime; Pi uses its own default thinking level.

Model Precedence

From highest to lowest priority:

1. Skill-level model 2. [defaults.agent] model 3. [defaults] model (legacy fallback) 4. CLI --model flag 5. WARDEN_MODEL env var 6. SDK default

Environment Variables

Native provider env vars (e.g. OPENAI_API_KEY) also work. The WARDEN_-prefixed forms are preferred in CI so they do not collide with locally-set provider keys.

Troubleshooting

No findings reported:

• Check --report-on threshold (default shows all)
• Verify skill matches file types in paths
• Use -v to see which files are being analyzed

Files being skipped:

• Built-in scan policy: lock files, minified, node_modules/, dist/
• Check [defaults.ignore].paths and skill ignorePaths in config
• Use -vv to see skip reasons

Token/cost issues:

• Reduce maxTurns (default: 50)
• Lower [defaults.agent].effort when the runtime supports cheaper reasoning levels
• Use chunking settings to control chunk size
• Filter to relevant files with paths

Creating Skills

Skills are markdown files that tell Warden what to look for. They follow the agentskills.io specification.

Skill Discovery

Warden searches these directories in order (first match wins):

.warden/skills/{name}/SKILL.md   # Warden-local generated skills
.agents/skills/{name}/SKILL.md   # Primary (recommended)
.claude/skills/{name}/SKILL.md   # Backup (Claude Code convention)

If no repo-local skill matches, names fall back to Warden's built-in skills such as security-review.

SKILL.md Format

---
name: my-skill
description: What this skill analyzes
allowed-tools: Read Grep Glob
---

[Analysis instructions for the agent]

## What to Look For
- Specific issue type 1
- Specific issue type 2

## Output Format
Report findings with severity, location, and suggested fix.

Available Tools

Read, Glob, Grep, WebFetch, WebSearch, Bash, Write, Edit

Most review skills only need Read, Grep, and Glob for exploring context.

Writing Checklist

• One skill, one concern ("security review" not "code quality")
• Clear criteria for what counts as an issue and at what severity
• Actionable findings that include how to fix
• Examples of good and bad code where helpful

Remote Skills

Skills can be fetched from GitHub repositories:

# Add a remote skill
warden add --remote <org>/<repo> --skill <skill-name>

# Add with version pinning (recommended for reproducibility)
warden add --remote <org>/<repo>@<ref> --skill <skill-name>

# List skills in a remote repo
warden add --remote <org>/<repo> --list

# Update all unpinned remote skills
warden sync

# Update specific repo
warden sync <org>/<repo>

# Run with cached skills only (no network)
warden --offline

Remote skill in warden.toml:

[[skills]]
name = "my-skill"
remote = "<org>/<repo>@<ref>"

[[skills.triggers]]
type = "pull_request"
actions = ["opened", "synchronize"]

Cache location: ~/.local/warden/skills/ (override with WARDEN_STATE_DIR)

Cache TTL: 24 hours for unpinned refs (override with WARDEN_SKILL_CACHE_TTL in seconds)

Warden Skill Sources

Source Inventory

Coverage Matrix

Decisions

• Keep SKILL.md as a quick router because agents often need only a command, not the full CLI documentation.
• Keep CLI, config, schema, and skill creation in separate references so agents can load only the relevant detail.
• Keep Warden-specific skill creation guidance in this skill even though generic skill authoring belongs elsewhere, because Warden has its own discovery, config, and remote-skill behavior.

Open Gaps

• Add or verify an auth/setup troubleshooting reference if repeated agent runs fail before Warden can execute.
• Confirm CLI examples after each release that changes flags, output modes, or init/add/sync behavior.
• Add migration notes if Warden introduces breaking config changes beyond version = 1.

Changelog

• 2026-04-27: Reverse-engineered maintenance spec and source inventory from the distributed warden skill.

Warden Skill Specification

Intent

The warden skill teaches coding agents how to run Warden during local development, interpret its output, and update Warden configuration or skill definitions when asked.

It exists as the lightweight runtime companion to the Warden CLI. The skill should get agents to the right command or reference quickly without duplicating the full product documentation.

Scope

In scope:

• Running Warden against uncommitted changes, explicit files, or git refs.
• Reading and editing warden.toml.
• Explaining Warden CLI flags, exit codes, severity thresholds, and output modes.
• Creating or wiring local Warden analysis skills.
• Directing agents to focused bundled references for detailed CLI, config, and skill-authoring behavior.

Out of scope:

• Replacing Warden product documentation.
• Running full-repository batch sweeps; use warden-sweep for that workflow.
• Defining project-specific review policy.
• Teaching generic agent skill authoring beyond Warden-specific discovery and config.

Users And Trigger Context

• Primary users: coding agents working in repositories that use Warden.
• Common user requests: "run warden", "check my changes", "review before commit", "update warden.toml", "add a Warden trigger", "create a Warden skill".
• Should not trigger for: ordinary code review requests with no Warden context, generic testing, PR writing, or full-repository sweep requests.

Runtime Contract

• Required first actions:
• Identify whether the user wants to run Warden, edit config, inspect output, or create/update a Warden skill.
• Load only the reference needed for that task.
• Prefer local repository configuration over generic examples.
• Required outputs:
• For runs: summarize command used, findings count, failure threshold, and next action.
• For config edits: state the changed trigger or setting and how to validate it.
• For skill creation: state where the skill was created and how it is referenced.
• Non-negotiable constraints:
• Do not loop Warden repeatedly on unchanged work.
• Do not invent config fields; check references/config-schema.md for exact names.
• Do not treat Warden findings as advisory text to suppress; fix the code or explicitly explain why a finding is not actionable.
• Expected bundled files loaded at runtime:
• references/cli-reference.md
• references/configuration.md
• references/config-schema.md
• references/creating-skills.md

Source And Evidence Model

Authoritative sources:

• Warden CLI behavior in src/cli/.
• Warden config loading and schemas in src/config/ and src/types/.
• Documentation pages in packages/docs/src/pages/.
• Existing runtime references in skills/warden/references/.

Useful improvement sources:

• positive examples: agent sessions where Warden was run once, findings were fixed, and config edits used valid schema fields
• negative examples: repeated Warden reruns with no changes, invented config fields, stale CLI flags, or generic skill instructions that do not match Warden discovery
• commit logs/changelogs: CLI flag changes, config schema changes, and skill discovery changes
• issue or PR feedback: reports of confusing Warden setup, missing command coverage, or stale agent skill docs
• eval results: local prompts covering run, config, output interpretation, and skill creation paths

Data that must not be stored:

• secrets, tokens, or API keys
• customer data
• private repository URLs or identifiers not needed for reproduction
• raw Warden logs containing sensitive code or findings

Reference Architecture

• SKILL.md contains task routing, quick commands, core constraints, and the reference map.
• SOURCES.md contains source inventory, coverage, gaps, and changelog.
• references/ contains focused CLI, config, schema, and Warden skill creation guides.
• references/evidence/ is unused until repeated examples need durable storage.
• scripts/ is unused; this skill delegates execution to the installed warden CLI.
• assets/ is unused.

Evaluation

• Lightweight validation:
• Run the skill validator against skills/warden.
• Check that every referenced bundled file exists.
• Spot-check CLI flags and config fields against source or generated docs.
• Deeper evaluation:
• Exercise prompts for running Warden, adding a trigger, explaining output, and creating a skill.
• Holdout examples:
• Preserve only redacted examples if recurring failures appear.
• Acceptance gates:
• SKILL.md stays concise and routes to focused references.
• Long references include navigation.
• Config examples use valid field names.
• Trigger description catches Warden-specific local development tasks without matching generic code review.

Known Limitations

• The skill assumes the warden CLI is installed and authenticated where required.
• CLI and config details can drift when source changes without updating the bundled references.
• Some host agents expose different skill-root variables; references are written as bundled file paths, while examples may need host-specific substitution.

Maintenance Notes

• Update SKILL.md when task routing, trigger language, or universal run constraints change.
• Update SOURCES.md when source inventory, decisions, coverage, or gaps change.
• Update references when CLI flags, config fields, remote skill behavior, or examples change.
• Update references/evidence/ only for durable positive or negative examples that should guide future iterations.