<p align="center">
<img src="assets/banner.png" alt="OpenWarden banner" width="100%" />
</p>
# OpenWarden
OpenWarden packages the **Warden pattern**: a general-purpose AI agent profile for keeping autonomous work aligned with a canonical source of truth.
A Warden is not an implementation bot. It is a recurring reviewer that reads the project’s canonical issue, roadmap, RFC, or brief; compares active work against that direction; flags drift; recommends cancellation when needed; and leaves a short, evidence-backed review note so humans can re-enter the project quickly.
> Unchecked agents create motion. Warden creates direction.
## Why this exists
AI agents are increasingly good at continuing work, opening PRs, creating issues, and proposing new architecture. The failure mode is no longer only “the agent cannot do enough.” It is also:
- the agent keeps moving after the goal changed;
- multiple agents create parallel but incompatible work;
- roadmap comments turn into unreviewed scope expansion;
- completed-work claims lack evidence;
- nobody can tell what should happen next.
OpenWarden turns direction-keeping into an explicit reusable agent role.
## The Warden loop
1. **Read the SSOT** — extract the goal, current phase, accepted direction, rejected direction, open questions, constraints, and non-goals.
2. **Scan active surfaces** — inspect open issues, PRs, comments, branches, automation runs, tasks, or agent outputs.
3. **Compare against direction** — classify each item as `aligned`, `needs-review`, `drifting`, `misaligned`, or `blocked`.
4. **Act narrowly** — prefer comments, labels, checklists, small follow-up issues, and review notes over broad implementation.
5. **Stop drift** — cancel or recommend pausing work that conflicts with the canonical direction.
6. **Report for human re-entry** — leave a compact bottom line, evidence, and next action.
## What a Warden can and cannot do
A Warden may:
- summarize the canonical direction;
- classify open work against that direction;
- detect missing evidence, stale assumptions, and scope drift;
- recommend cancellation or pausing;
- add review notes and small next-step proposals;
- update a checklist when explicitly authorized.
A Warden should not:
- act as the product owner;
- rubber-stamp agent-generated work;
- merge, approve, force-push, or force-close without explicit authorization;
- create large implementation PRs as part of a review pass;
- invent a new roadmap when the SSOT already exists.
## Quick start
Copy [`profiles/warden.md`](profiles/warden.md) into your agent system prompt, project skill, or recurring scheduled job.
For Hermes, install or copy the packaged skill from
[`skills/openwarden/SKILL.md`](skills/openwarden/SKILL.md). Then give Hermes the
canonical SSOT issue link:
```bash
hermes chat --skills openwarden -q \
'Use https://github.com/OWNER/REPO/issues/123 as the SSOT and run a Warden review.'
```
See [`examples/hermes-ssot-warden-prompt.md`](examples/hermes-ssot-warden-prompt.md)
for a reusable one-shot and recurring-job prompt.
Minimal prompt:
```text
You are the Warden for this project.
Canonical source:
<issue/doc/RFC URL or pasted text>
Active surfaces to inspect:
- open PRs
- open issues
- recent comments
- recent automation runs
Policy:
- preserve the canonical direction;
- prefer evidence over claims;
- classify work as aligned, needs-review, drifting, misaligned, or blocked;
- recommend cancellation for drift;
- do not approve, merge, force-close, or force-push unless explicitly authorized.
Output:
- bottom line;
- aligned work;
- needs-review items;
- cancelled/misaligned items;
- recommended next action.
```
## Example output
```markdown
## Warden review — 2026-05-17
### Bottom line
The project is still aligned with the SSOT, but two active branches should pause until their evidence claims are tied to the canonical gate.
### Aligned work
- PR #42 — implements the accepted runtime slice and includes test evidence.
### Needs review
- Issue #43 — directionally plausible, but missing a concrete acceptance gate.
### Cancelled or should stop
- Branch `agent/refactor-everything` — broad rewrite not authorized by the SSOT.
### Recommended next action
1. Land the narrow evidence-gate fix.
2. Update the SSOT checklist with the verified result.
```
## Case study: GitHub issue #961
The pattern was extracted from how we used a public GitHub issue as a live roadmap control surface:
- **Issue:** [Q00/ouroboros#961 — “Meta SSOT: AgentOS roadmap sequencing (#920–#960)”](https://github.com/Q00/ouroboros/issues/961)
- **Role:** the issue acted as the canonical source of truth for the AgentOS roadmap.
- **Problem:** many related issues and PRs existed at once, and the project needed a way to prevent direction drift while still allowing narrow implementation slices.
- **Warden behavior:** periodically read #961, inspect open issues/PRs/comments, decide which work matched the roadmap, flag broad or stale proposals, and leave short review notes that linked evidence back to the SSOT.
- **Practical result:** #961 became a re-entry surface for humans and agents: “what is still open?”, “what is blocked?”, “which PRs are already merged?”, and “what should not be started yet?” could be answered from one place.
See [`examples/issue-961-case-study.md`](examples/issue-961-case-study.md) for a more detailed breakdown.
## Repository layout
```text
profiles/warden.md Portable Warden agent profile
skills/openwarden/SKILL.md Hermes skill for SSOT-based Warden runs
examples/hermes-ssot-warden-prompt.md Hermes one-shot and recurring prompt
examples/issue-961-case-study.md Public case study using Q00/ouroboros#961
README.md Project overview
LICENSE MIT license
```
## When to use OpenWarden
Use it when your project has:
- a roadmap issue, RFC, project brief, Linear/Jira epic, Notion page, or other SSOT;
- multiple humans or agents working in parallel;
- recurring review needs;
- risk of over-automation or architectural drift;
- a need for calm cancellation notes instead of runaway execution.
Do not use it for one-off tasks with no coordination burden.
## License
MIT