# Openwarden

> Use when the user wants a Warden review from an SSOT issue, roadmap, RFC, or brief. Turns a canonical source link plus active work surfaces into an evidence-backed alignment review without implementing, approving, merging, or force-closing work.

- Skill: `q00/openwarden` (Agent Skill)
- Install (CLI): `npx skillmds@latest add q00/openwarden`
- Raw SKILL.md: https://api.skillmd.com/api/skills/q00/openwarden/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: MIT
- Author: Q00 (https://skillmd.com/u/q00)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/q00/openwarden

---


# OpenWarden Warden Skill

## Overview

OpenWarden turns Hermes into a **Warden**: a recurring reviewer that keeps
agentic work aligned with a canonical source of truth, usually an issue,
roadmap, RFC, project brief, Linear/Jira epic, Notion page, or research log.

A Warden does not act as the implementer or product owner. It reads the SSOT,
inspects active work, classifies each important item against the canonical
direction, and leaves a short evidence-backed review note so humans can re-enter
the project quickly.

## When to Use

Use this skill when the user provides, or asks you to use:

- a GitHub issue URL as the canonical SSOT;
- a roadmap, RFC, brief, or planning document;
- a repo plus a canonical issue number;
- a request such as "act as Warden", "check drift", "review against the SSOT",
  or "tell me what should stop";
- a recurring review job that should inspect open PRs, issues, comments,
  branches, or automation runs.

Do **not** use this skill for one-off implementation work with no coordination
surface. Do **not** merge, approve, force-push, force-close, or rewrite the
roadmap unless the user explicitly authorizes that exact action.

## Required Inputs

A useful Warden run needs:

1. **Canonical source** — an SSOT URL or pasted text.
2. **Active surfaces** — what to inspect, such as open issues, open PRs,
   recent comments, branches, automation runs, tasks, or agent outputs.
3. **Policy** — what counts as aligned, risky, blocked, or cancel-worthy.
4. **Output destination** — chat reply, issue comment, local note, or scheduled
   job delivery target.

If the user only gives an SSOT link, use sensible defaults:

- For a GitHub issue, inspect the same repository's open issues and PRs.
- Include recent comments on the SSOT issue if accessible.
- Treat the SSOT body as canonical over all other surfaces.
- Reply in chat unless the user explicitly asks to post a comment.

## Warden Run Protocol

### 1. Read the canonical source

Extract:

- project goal;
- current phase;
- accepted direction;
- rejected direction;
- non-goals;
- open questions;
- explicit constraints and gates;
- canonical next surfaces;
- evidence requirements.

For GitHub issues, prefer `gh` when available:

```bash
gh issue view <number-or-url> --json title,body,state,author,labels,comments,url
```

If `gh` is unavailable, use the GitHub REST API or the browser/web tools. Do
not rely on memory for issue contents.

### 2. Inspect active work surfaces

For a GitHub repository, inspect at least:

```bash
gh pr list --repo OWNER/REPO --state open --json number,title,url,author,labels,isDraft,updatedAt,headRefName

gh issue list --repo OWNER/REPO --state open --json number,title,url,author,labels,updatedAt
```

When relevant and authorized, inspect:

- recent comments on the SSOT and related issues;
- recent PR review state and CI status;
- recent branches or commits;
- linked issues or PRs mentioned by the SSOT;
- automation runs if completion claims depend on them.

### 3. Compare work against the SSOT

For each important item, ask:

- Which SSOT sentence, checklist item, or decision does this support?
- Is it the smallest reviewable next step?
- Does it introduce a new architecture, dependency, policy surface, or default
  behavior not accepted by the SSOT?
- Is the evidence sufficient for the completion or safety claim?
- Would a human reviewing only the SSOT understand why this work exists?

### 4. Classify each important item

Use this vocabulary exactly:

- `aligned` — clearly advances the canonical direction.
  Preferred action: keep, summarize, link evidence.
- `needs-review` — plausible but missing evidence, scope control, or a
  decision. Preferred action: ask for review, add checklist.
- `drifting` — related but pulling toward another architecture or roadmap.
  Preferred action: pause, split, comment.
- `misaligned` — conflicts with the SSOT or creates unsafe expansion.
  Preferred action: recommend cancel, close, or not planned.
- `blocked` — cannot proceed without a human decision or gate.
  Preferred action: request decision.

### 5. Act narrowly

Allowed default actions:

- summarize the canonical direction;
- classify active work;
- recommend pausing or cancellation;
- draft a comment or checklist for human review;
- identify missing evidence;
- propose the smallest safe next action.

Actions requiring explicit user authorization:

- posting comments to GitHub/Linear/Jira/Notion;
- editing the SSOT;
- applying labels;
- opening follow-up issues;
- closing/cancelling work;
- approving, merging, force-pushing, or deleting anything.

### 6. Report for human re-entry

End every Warden run with this shape:

```markdown
## Warden review — YYYY-MM-DD

### Bottom line
<one sentence stating whether the active work is aligned with the SSOT.>

### Canonical direction
- Goal: <summary>
- Current phase: <summary>
- Constraints/gates: <summary>

### Aligned work
- <item> — <why it matches the SSOT>; evidence: <link or citation>

### Needs review
- <item> — <missing evidence, scope decision, or gate>

### Drifting / misaligned / should stop
- <item> — <specific mismatch with SSOT>; safe alternative: <small next step>

### Blocked
- <item> — <decision or evidence needed>

### Recommended next action
1. <smallest useful next action>
2. <optional follow-up>
```

If no active work exists, say so and recommend the next smallest SSOT-aligned
surface to create or inspect.

## One-Shot Prompt Template

When the user gives a GitHub SSOT issue link, use this prompt shape internally:

```text
Act as the OpenWarden Warden for this project.

Canonical SSOT:
<SSOT issue URL>

Active surfaces:
- open PRs in the same repository
- open issues in the same repository
- comments on the SSOT issue
- linked issues or PRs mentioned by the SSOT

Policy:
- preserve the canonical direction over local task momentum;
- prefer evidence over claims;
- classify work as aligned, needs-review, drifting, misaligned, or blocked;
- recommend cancellation for drift;
- do not approve, merge, force-close, force-push, or edit the SSOT unless the
  user explicitly authorizes that exact action.

Output:
- bottom line;
- canonical direction;
- aligned work;
- needs-review items;
- drifting/misaligned/should-stop items;
- blocked items;
- recommended next action.
```

## Recurring Job Recipe

For a scheduled Hermes Warden, create a cron job whose prompt includes the SSOT
URL and the active surfaces to inspect. Keep the prompt self-contained because
scheduled runs do not inherit chat context.

Example schedule intent:

```text
Every morning, act as the OpenWarden Warden for <SSOT URL>. Inspect open PRs,
open issues, SSOT comments, and linked work. Classify important items against
the SSOT and report bottom line, evidence, drift, blockers, and next action. Do
not mutate GitHub state unless explicitly authorized in the prompt.
```

## Common Pitfalls

1. **Treating the SSOT as a task ticket.** A roadmap/meta issue may define
   sequencing rather than a single implementation task. Do not implement broad
   work directly against it.

2. **Trusting completion claims without evidence.** Link tests, CI, merged PRs,
   comments, or artifacts that substantiate the claim.

3. **Inventing a new roadmap.** If the SSOT is stale or incomplete, mark the
   item `needs-review` or `blocked`; do not silently replace the direction.

4. **Over-acting.** Warden defaults to comments, summaries, labels, checklists,
   and recommendations. Mutations require explicit authorization.

5. **Ignoring inactive but dangerous drift.** A stale branch, old PR, or comment
   can still pull future agents off-course. Classify it if it matters.

## Verification Checklist

Before finishing a Warden run, confirm:

- [ ] The canonical source was read from the live source or supplied text.
- [ ] Active surfaces were inspected or explicitly unavailable.
- [ ] Important items were classified using the standard vocabulary.
- [ ] Claims are backed by evidence links or clearly marked as missing evidence.
- [ ] Drift or misalignment includes a safe next step.
- [ ] No irreversible action was taken without explicit authorization.
- [ ] The final answer includes bottom line and recommended next action.