gza-watch-docs

gza-watch-docs is a skill for Claude Code from mhawthorne/gza. It costs 33 tokens per session (1,199 once invoked), scanned A, original, MIT.

A documentation command that regenerates a description and diagram of the phases in the `gza watch` loop directly from its Python source code. It follows the actual phase order and implementation instead of relying on the old document.

In plain words
What is it for?
Use it after adding, removing, reordering, or changing a phase in `src/gza/cli/watch.py`, or when the watch-phase document needs updating.
Why use it?
It reduces the risk that internal documentation becomes different from the code it describes. This is useful because the document is maintained by hand and is not updated automatically.

Skill for Claude Code

Written for Claude Code: allowed-tools in frontmatter. Also seen: mentions subagents.

Good fit Use it after adding, removing, reordering, or changing a phase in src/gza/cli/watch.py, or when the watch-phase document needs updating.

Compare 6 skills from other repositories ↓
Install with agentmods
npx agentmods add skills/mhawthorne/gza/gza-watch-docs
Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

Any agent
npx skills add mhawthorne/gza --skill gza-watch-docs
Clone the repo
git clone --depth 1 https://github.com/mhawthorne/gza

Made for: Claude Code.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

agentmods badge for gza-watch-docs

README.md
[![agentmods](https://agentmods.dev/badge/skills/mhawthorne/gza/gza-watch-docs/github.svg)](https://agentmods.dev/skills/mhawthorne/gza/gza-watch-docs)
Your own site
<a href="https://agentmods.dev/skills/mhawthorne/gza/gza-watch-docs"><img src="https://agentmods.dev/badge/skills/mhawthorne/gza/gza-watch-docs/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

agentmods 80×15 button for gza-watch-docs

Your own site · 80×15
<a href="https://agentmods.dev/skills/mhawthorne/gza/gza-watch-docs"><img src="https://agentmods.dev/badge/skills/mhawthorne/gza/gza-watch-docs.svg" alt="Reviewed on agentmods" width="80" height="20"></a>
Per session 33 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 1,199 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5.1 $0.00033 $0.01199
Opus 5 $0.00016 $0.00600
Sonnet 5 $0.00007 $0.00240
Haiku 4.5 $0.00003 $0.00120

Measured 6d ago against content hash d427809b73ea, method: parsed. Prices are Anthropic first-party input rates as of 2026-09-12, from the pricing page.

Security

Grade A, and why

gza-watch-docs scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 6d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

src/gza/skills/gza-watch-docs/SKILL.md · 104 lines

How it starts

The opening of the file, as written. The whole thing — 104 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Gza Watch Docs

Regenerate docs/internal/generated/watch-cycle-phases.md — the description of what gza watch's main loop does — directly from src/gza/cli/watch.py.

This exists because that doc is hand-derived and nothing keeps it in sync with watch.py automatically. Run this skill after changes to watch.py's phase structure (new phases, removed phases, reordering, or changes to what a phase touches) instead of writing the doc up from scratch in conversation.

When to use

  • User asks to "regenerate the watch docs" or "update the watch-phases doc"
  • Before/after a change that adds, removes, reorders, or changes what a _run_cycle phase does in src/gza/cli/watch.py

Process

Step 1: Find the phase list and orchestration order

Read src/gza/cli/watch.py's _run_cycle function (search for def _run_cycle) to get the current ordered list of phases it invokes. This is the ground truth for phase order — do not rely on the previous version of the doc for ordering.

Step 2: For each phase, find its implementation

For each phase name found in Step 1, locate the function/block that runs during that phase (grep for the phase's log-emitted name, e.g. "cycle-plan", "lifecycle-preflight", "blind-parked-auto-rearm"). For each one, determine:

  • What DB reads/writes happen (calls into SqliteTaskStore / store.*)
  • What git subprocess calls happen (calls into a git.* helper, or direct subprocess invocations of git)
  • What disk/filesystem checks happen outside git (config files, installed package version/hash)
  • What process spawns happen (worker subprocess launches, proc/PID checks)
  • Roughly why the phase is fast or slow (one query vs. per-item subprocess calls vs. running an external command like the verify/test suite)

Use Explore subagents to parallelize this across phases if there are many — don't read the whole 15,000+ line file serially in the main context.

Step 3: Find the cycle-boundary / re-exec behavior

Find where the outer while-loop calls _run_cycle and where drift/re-exec is checked (search for _should_reexec_watch or similar). Confirm whether re-exec still happens only at the cycle boundary (after _run_cycle returns) or whether that's changed.

Read the full file on GitHub · 104 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 6d ago First seen · 104 lines · 33 tokens per session scan A d427809b73ea

Subscribe to this mod's changes

gza-watch-docs is a skill published in the GitHub repository mhawthorne/gza (12 stars, last pushed 2d ago), licensed MIT. It adds 33 tokens to every session and 1,199 once invoked, about $0.0002 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-09-06.