Agents, skills, and operational tools

This repository is James Gardner's installable agent workspace: specialized agent definitions, reusable skills, the scripts that validate and symlink them, and a small number of operational tools developed beside the workflows they support.

• agents/ — focused subagent definitions with enforced tool posture.
• skills/ — user-invocable workflows such as review, handoff, and work-board access.
• scripts/ — lint, generation, and idempotent local installation.
• hud/ — the work-HUD server and its authoring skill; the content it renders lives in a private tree outside this repository.
• work-board/ — a workerd-native UI staged here before transfer to Canonical Hours.

Install

scripts/install.sh
scripts/install.sh --apply
scripts/install.sh --doctor

install.sh is idempotent. Re-run any time you pull. Use --doctor to find broken symlinks left over from path moves.

Agents

Generated by scripts/build.sh readme. Edit the source file's frontmatter, not the table below.

Agent	Model	Color	Purpose
adversarial-synthesis-lead	opus	red	Use this agent to integrate findings from the six adversarial reviewers (dos-resilience-auditor, enumeration-oracle-hunter, bundle-isolation-tester, protocol-replay-adversary, trust-root-adversary, observability-gap-auditor), reconcile overlaps, prioritize, and promote findings into the threat-model + ADR record.
bundle-isolation-tester	opus	red	Use this agent for adversarial analysis of cross-tenant isolation in workerd-style hypervisors — slice-grant escapes, manifest misconfig exploitation, service-binding leakage, identity-confusion at the syscall boundary.
dataflow-driven-troubleshooting	opus	green	Use this agent to trace a reported symptom BACKWARD through the dataflow to the site that originates it, verify the load-bearing facts against primary sources, and terminate in an attributed disposition — root cause, fix-owner, and ticket action — not just an investigation write-up.
design-doc-reviewer	opus	purple	Use this agent to review a design doc, RFC, ADR, or technical proposal for the DECISION it asks you to ratify — not the prose.
documentation-synthesis-architect	inherit	blue	Use this agent when you have sprawling, overlapping, or fragmented documentation that needs consolidation, restructuring, and distillation into coherent, non-redundant artifacts.
dos-resilience-auditor	opus	red	Use this agent for adversarial analysis of resource-exhaustion attack vectors in agent-hosting substrates — self-DoS via legal exits, single-threaded handler saturation, queue-depth attacks, fairness violations.
empirical-validation-designer	inherit	—	Translates theoretical claims into concrete, executable experiments that produce real results on real hardware
enumeration-oracle-hunter	opus	red	Use this agent to find side-channel and response-shape oracles that let an attacker enumerate names, existence, or relationships in a multi-tenant substrate.
experimental-design-architect	inherit	magenta	Specializes in translating high-level research philosophy into concrete, falsifiable, and scalable experimental protocols
observability-gap-auditor	opus	red	Use this agent for adversarial analysis of observability and alerting gaps — silent denial paths, alert deadlock under load, 'silence is evidence' invariants that break when the silence is from the substrate not the absence of activity.
paradigm-assessor	opus	red	Use this agent for a high-skepticism, 'red-team' audit of a novel 'paradigm-defining' framework.
platform-archaeologist	inherit	orange	Build complete infrastructure memory by traversing repositories and mapping all dependencies, migrations, and patterns.
platform-code-reviewer	inherit	green	Use this agent for reviewing Go, Terraform, and GCP infrastructure code with a focus on semantic correctness, not just syntax.
pr-reviewer	inherit	cyan	Reviews a SINGLE pull request in an isolated git worktree and returns a structured verdict — never posts to GitHub.
production-readiness-reviewer	inherit	blue	Use this agent when you need a comprehensive production readiness assessment of code before deployment.
protocol-replay-adversary	opus	red	Use this agent for adversarial analysis of protocol-state attacks — lease replay across windows, nonce-ledger gaps, epoch confusion, clock-skew exploitation, partial-failure replay across cross-DO orchestrators, receipt-chain forks.
repo-seo-curator	inherit	yellow	Use this agent to improve repository discoverability for the three audiences that find code: humans skimming GitHub/HN/search results, AI agents and LLMs ingesting context, and search engine crawlers.
research-paper-reviewer	inherit	green	Use this agent when you need expert-level review and analysis of academic papers, research proposals, or technical documents.
research-paper-writer	inherit	blue	Use this agent when you need to write academic papers, research reports, or technical manuscripts based on experimental results.
review-pattern-surfacer	inherit	magenta	Use this agent to analyze code review patterns from any GitHub user across specified repositories.
security-auditor	opus	red	Use this agent when you need adversarial security analysis of infrastructure, authentication flows, supply chain integrity, key management, or deployment configurations.
surgical-reviewer	inherit	cyan	Use this agent when you need precise, no-nonsense code review that focuses exclusively on necessary improvements.
theoretical-foundations-analyst	opus	purple	Use this agent when you need rigorous theoretical analysis of complex mathematical or computational systems, cross-disciplinary problem solving, or fundamental correctness review of novel approaches.
trust-root-adversary	opus	red	Use this agent for adversarial analysis of supply-chain and trust-root compromise scenarios — helper binary tamper, keystore confusion, CA bundle poisoning, kid (key-id) confusion, signer rotation races.
type-driven-correctness	opus	blue	Use this agent to audit whether a codebase's invariants are carried by the strongest mechanism available — a type that makes the violation unrepresentable > a transaction boundary > a machine-checked property > a named example test > prose.

Skills

Generated by scripts/build.sh readme. Edit the source file's frontmatter, not the table below.

Skill	Tool grant	Purpose
break-glass	prompts	Emergency IAM elevation for oncall/debugging.
claim-ledger	pre-approved	Before opening a PR, enumerate every behavior it claims — stated, callers- unaffected, invariants-preserved — and tag each with the strongest evidence actually held: RAN, READ, or ASSUMED with a closed-set reason.
contract-parity-audit	prompts	Use when one interface/trait has multiple implementations that are assumed equivalent (storage backends, providers, transports), when several public surfaces (CLI/API/webhook/worker) expose the same verb, when bugs cluster as "works on X but not Y", or to scope a guardrail-parity fix before estimating it.
counterfactual-audit	prompts	Use when asked whether a repo's architecture is still right — a counterfactual "how would this be designed today?" question, a suspicion of over/under-engineering or monolith-vs-split, recurring bug families that smell structural, or before committing to a major refactor.
design-doc-review	pre-approved	Review a design doc for the decision it asks you to ratify — not the prose.
diagram-gen-emergent	pre-approved	Generate a bottom-up diagram of actual code coupling from cross-references — what the code does, not what was intended.
diagram-gen-spec	pre-approved	Generate a top-down diagram of intended architecture from a mache schema file — what the PR proposes, not what the code does.
doc-triage	prompts	Find internal docs (not for external consumers), review against code reality, bead real items, archive stale files.
explain-work	pre-approved	Review a PR, ticket, or path and explain it so it sticks — mache/CODEOWNERS/ ticket context synthesized into a taught explanation, not a bare findings list.
feature-impl	prompts	Research-first feature implementation workflow.
first-party-audit	pre-approved	Before writing glue, a wrapper, or a "small helper", audit whether the capability already exists first-party — in the binary, the codebase, or the platform — and whether existing glue bypasses a better first-party implementation.
handoff	pre-approved	Compact a session into a handoff at the work SEAM — where this session ends and the next resumes.
hud	prompts	Capture a note, playbook, peer, or project-context update into the user's personal work HUD — a local markdown tree at $HUD_ROOT.
implement	prompts	Deterministic end-to-end implementation orchestrator.
jj-stack	pre-approved	Turn one dev branch into small, individually-reviewable stacked PRs that land on a feature branch (one final merge to main), using jujutsu (jj) colocated with git plus keyless commit signing.
linear-escalation-triage	pre-approved	Use for Linear tickets assigned to you — oncall queue sweeps, aged P1/P2 escalations in Triage > 7 days, stale Todos needing cleanup, or an external escalation (Slack/support) surfacing a ticket needing a triaged reply.
mache-usage	pre-approved	Start or locate a running mache MCP server for a source path or .db file.
park-work	pre-approved	Check whether the current human-agent work episode is mechanically safe to close, park incomplete work behind a verified durable checkpoint and receipt, or inspect a previously parked episode before a fail-closed resume gate.
pr-board	pre-approved	Answers "how are my PRs?", "did I address the review?", "anything waiting on me?".
pr-buckets	pre-approved	Group a body of in-progress work (a diff, a branch, a set of changes) into small, individually-reviewable PR buckets sized to a LoC threshold — one concern per bucket, in dependency order.
pr-review-kit	pre-approved	Self-contained playbook for rigorous PR review: state inspection, design-intent hunting, verification rules (cite sources, walk commits, verify artifacts), agent dispatch, falsifiable-matrix output, GitHub posting only with explicit authorization.
pr-review	pre-approved	Give or respond to PR reviews with structural awareness via mache.
pr-suggestion	pre-approved	Post a GitHub review comment as an applyable "suggested change" — a ```suggestion block the author commits with one click — and, first, decide whether a finding should be a suggestion at all.
prior-art-cartographer	pre-approved	Produce cited, structured comparisons between a project and external systems solving adjacent problems; updates a prior-art matrix.
problem-decomposer	pre-approved	Decompose an aspiration into dispatchable bead specs via 5-whys descent + a 7-property rubric.
readme-restructure	pre-approved	Restructure a README for human skimmers and LLM ingestion — fixes frontloaded internals, moves the value prop into the first 200 tokens, generates a diff for review.
repo-description-polish	pre-approved	Audit and polish the GitHub repo description — the pitch shown in search results, previews, and embeds.
repo-homepage-set	pre-approved	Audit and set the GitHub repo homepage URL — the link on the repo card's "About" panel and every search result.
repo-social-preview	pre-approved	Audit the GitHub OpenGraph social preview image shown when a repo URL is posted on HN/Twitter/Slack/Discord.
repo-topic-tagger	pre-approved	Audit and apply GitHub topic tags for discoverability — proposes tags from code signals, deduplicates against current tags, applies via gh api after explicit approval.
review-prep	pre-approved	Synthesize a PR's spec-driven diagram, emergent diagram, and impact analysis into reviewer context: what's proposed vs.
review-queue	prompts	Fan out isolated, one-per-PR reviews across your queue (own context + worktree per PR, no cross-pollution), then synthesize one report.
self-audit	pre-approved	Pre-review self-audit of a PR branch: dead struct fields, rotting comments, duplicate types, scope drift — what a human catches but a compiler won't — then dispatches an adversarial agent for deeper design flaws.
structural-pr-review	pre-approved	Deterministic PR-review chain with pluggable structural intelligence.
survey	prompts	Multi-perspective codebase survey that produces beads and mermaid diagrams from code structure.
taskfile-ci-parity	pre-approved	Wire validation so local == CI by construction: every check is a Taskfile target; CI and hooks invoke it rather than reimplementing it.
test-fidelity	pre-approved	Hunt vacuous / low-fidelity tests — the ones that pass whether or not the code is wrong in the way they claim to catch.
work-scope	pre-approved	Decompose feature work into reviewable, shippable PR-sized units before coding starts.
workflow-audit	pre-approved	Mine the user's Claude Code chat corpus for self-optimization patterns — repeated corrections, tool thrash, dropped threads — into a ranked, PII-scrubbed report.

How agents and skills differ

	Agent	Skill
Invocation	Claude delegates automatically based on description; you can also invoke with the Agent tool	/skill-name (you) or automatic (Claude reads description)
Context	Runs in a separate context window	Inlined into the current conversation (or forked via context: fork)
Scope	A persona with long-lived methodology	A workflow with arguments and (optional) scoped tool permissions
Frontmatter required	name, description	description (name defaults to directory)

For full semantics, see Anthropic's subagents and skills docs.

The work HUD (hud/)

hud/ is a local-only work HUD: one page that renders a markdown knowledge tree on the left and, on the right, panels for whatever local services you point it at — your pull requests, an activity digest, colleagues' PRs, your agent sessions, and which skills and agents are actually linked into ~/.claude. It is watch-only by construction: content routes are GET-only and tested to stay that way, and every "do" is a link out into the tool where a human acts.

The code is here; the content is not. This directory holds only the machinery — server, UI, tests, the launchd service scripts, the mache index projection, and the canonical hud skill that skills/hud symlinks to. Everything the HUD renders lives in a separate private tree selected by HUD_ROOT (default ~/hud), along with its hud.toml and everything the HUD writes back (snapshots, logs, indexes, all under a gitignored $HUD_ROOT/.generated/). That split is the point: notes about real work, real colleagues, and real tickets never enter this repository, and nothing here needs them to run.

Node stdlib only — no npm packages, no build step, no node_modules.

HUD_ROOT=~/hud node hud/server.mjs     # then open http://127.0.0.1:4870

You need a content tree first: a directory with a hud.toml and at least one content directory. hud/skills/hud/SKILL.md documents the tree's shape and is also the skill agents load to write into it correctly; a tree that already exists carries its own HUD.md, which wins over the skill on any conflict.

node --test hud/test/                  # hermetic suite; touches no real tree
bash hud/smoke.sh                      # 13 asserts against a real HUD_ROOT
bash hud/service/install.sh            # optional macOS launchd agent
bash hud/service/uninstall.sh          # leaves zero resident state

The service is sugar and nothing depends on it — node hud/server.mjs stays the canonical way to run the HUD, and the server has no idea launchd exists. hud/service/plist.template is a template with placeholders, not a live plist; the rendered one lands in ~/Library/LaunchAgents/ and is committed nowhere.

Creating agents, skills, and operational packages

Agent and skill frontmatter is validated against both the Anthropic Claude Code spec and the stricter Gemini CLI spec — unknown fields fail lint because Gemini rejects them.

Agent (agents/<name>.md):

---
name: my-agent
description: "When to use, with embedded <example> blocks Claude reads."
model: inherit          # or sonnet / opus / haiku / claude-<full-id>
color: blue             # red blue green yellow purple orange pink cyan magenta
---

System prompt for the persona…

If the persona calls a known MCP server's tools (rsry_*, mache_*, or the fully-qualified mcp__server__tool form), document it with a **MCP dependency:** line in the body — scripts/build.sh lint fails any agent that calls one without declaring it, so the dependency can't drift silently out of the frontmatter/prose. For agents that should never write source (read-only reviewers, "find it, file a bead, never patch" personas), also add disallowedTools: Write, Edit to the frontmatter so the constraint is enforced, not just promised in prose. See agents/dos-resilience-auditor.md for both in practice.

Skill (skills/<name>/SKILL.md):

---
name: my-skill
description: Trigger phrases and what this does.
allowed-tools: Bash Read Grep
argument-hint: <required> [optional]
---

Workflow body. `$ARGUMENTS` is substituted at invocation.

Operational package (for example, work-board/):

Keep an operational package isolated behind its own package manifest, runtime configuration, tests, and README. It may be developed beside the workflow that uses it while ownership is being established, but it is not installed as an agent or skill and must document its intended long-term owner.

Run scripts/build.sh before committing agent or skill changes — it lints frontmatter and regenerates the tables above. Run the operational package's own documented check separately.

Development

scripts/build.sh lint        # validate frontmatter only
scripts/build.sh readme      # regenerate README tables only
scripts/build.sh             # both (default)

scripts/install.sh           # dry-run: show planned symlinks
scripts/install.sh --apply   # create/update symlinks in ~/.claude/
scripts/install.sh --doctor  # remove broken symlinks (with --apply)

A pre-commit hook is configured in .pre-commit-config.yaml:

brew install pre-commit   # or: pip install pre-commit
pre-commit install

License

MIT — see LICENSE.