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.
• 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.
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 scope	Purpose
break-glass	inherits all	Emergency IAM elevation for oncall/debugging.
diagram-gen-emergent	scoped	Generate a bottom-up community diagram from real code cross-references.
diagram-gen-spec	scoped	Generate a top-down structural diagram from a mache schema file.
doc-triage	inherits all	Find internal docs (not for external consumers), review against code reality, bead real items, archive stale files.
explain-work	scoped	Review a unit of work (a PR, a Linear ticket, or a path) and explain it so it sticks — composing structural context (mache/seams), team ownership (CODEOWNERS), and intent (the ticket) into a taught synthesis rather than a bare findings list.
feature-impl	inherits all	Research-first feature implementation workflow.
handoff	scoped	Compact the current session into a handoff anchored at the work SEAM — the joint where this session ends and the next begins.
linear-escalation-triage	scoped	Use when handling Linear tickets assigned to you — during weekly oncall queue sweeps, when picking up a specific aged escalation (P1/P2 in Triage > 7 days), when cleaning up stale Todos where work may have landed elsewhere, or when an external escalation (Slack ping, support comment) surfaces a ticket needing a triaged customer-facing reply.
mache-usage	scoped	Start or locate a running mache MCP server for a source path or .db file.
pr-board	scoped	Use when you ask "how are my PRs?", "did I address Mark's review?", "what's new on the PRs I opened?", or "anything waiting on me?" — the recurring authored-PR status question.
pr-review-kit	scoped	Self-contained playbook for rigorous PR review.
pr-review	scoped	Give or respond to PR reviews with structural awareness via mache.
prior-art-cartographer	scoped	Produce structured comparisons between a project being built (described by a baseline doc) and external systems that solve adjacent problems.
problem-decomposer	scoped	Decompose an aspiration into a lattice of dispatchable bead specs using 5-whys descent + a 7-property dispatchability rubric.
readme-restructure	scoped	Restructure a README for both human skimmers and LLM ingestion.
repo-description-polish	scoped	Audit and polish the GitHub repository description — the one-sentence pitch shown in search results, link previews, and embeds.
repo-homepage-set	scoped	Audit and set the GitHub repository homepage URL — the link on the repo card's "About" panel and on every search result.
repo-social-preview	scoped	Audit the GitHub OpenGraph social preview image — the card shown when a repo URL is posted on HN, Twitter, Slack, or Discord.
repo-topic-tagger	scoped	Audit and apply GitHub topic tags (repository topics) on a target repo for discoverability — proposes tags from code signals, deduplicates against current tags, and applies via gh api after explicit user approval.
review-prep	scoped	Given a PR number or diff, synthesize spec-driven diagram, emergent diagram, and impact analysis into a structured insight: block for the reviewer.
review-queue	inherits all	Fan out isolated, one-per-PR code reviews across your review queue, then synthesize.
self-audit	scoped	Pre-review self-audit of a PR branch.
survey	inherits all	Multi-perspective codebase survey that produces beads and mermaid diagrams from code structure.
taskfile-ci-parity	scoped	Wire repo validation so local == CI by construction - every check is a Taskfile target, and CI + git hooks INVOKE those targets rather than re-implementing the commands.
work-scope	scoped	Decompose feature work into reviewable, shippable units before coding starts.
workflow-audit	scoped	Mine the user's Claude Code chat corpus for self-optimization patterns — repeated corrections, tool thrash, dropped threads, restated constraints — and produce a ranked, PII-scrubbed, anti-recency-biased markdown 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.

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.