agents

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. Emphasis shifts by authorship: work you own gets domain-onboarding (so you can defend it in a meeting); a peer's gets findings-teaching (so you learn to spot it yourself). Reads your situated context from native user rules + auto-memory when present and degrades gracefully without it. Local/explain only — posts nothing, edits nothing.

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. Use when adding a test/lint/format/validation gate, when CI and local disagree, when a pre-commit/pre-push hook duplicates a command, or when asked to make validation 1:1 with CI, add a Taskfile target, or stop CI failing first. Covers includes-vs-composition, the non-mutating task ci gate, and the pre-push hook pattern.

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. Answers it lectio-first via memory_authored_activity (reviews/comments by OTHERS on PRs you authored, your own replies excluded), refreshes the gh source if it's stale, joins each PR to your local worktrees + notes, and prints a board of what needs you. Falls back to gh only for coverage gaps. Read-only; posts nothing.

Find internal docs (not for external consumers), review against code reality, bead real items, archive stale files. Converts markdown debt into tracked beads.

Decompose an aspiration into a lattice of dispatchable bead specs using 5-whys descent + a 7-property dispatchability rubric. Outputs a problem-statement doc (matching TEMPLATE.md), a list of bead specs ready to file via rosary:note, and an honest queue of non-leaves that need further design. Use when starting a new platform / capability / migration / refactor where work needs to be broken down before agents can ship it. Use also to audit an existing backlog for orphan-dispatchable beads that don't trace to a real aspiration.

Restructure a README for both human skimmers and LLM ingestion. Diagnoses information architecture, identifies frontloaded internals, proposes a reordered structure that lands the value prop in the first 200 tokens, then generates a diff for review. Preserves content; changes order and disclosure. Modular sub-skill of repo-seo-curator.

Fan out isolated, one-per-PR code reviews across your review queue, then synthesize. Use when you have several peer PRs to review and want each in its own context + git worktree (no cross-PR pollution), with a single consolidated report at the end. Dispatches the pr-reviewer sub-agent (isolation worktree, read-only) per PR; pulls the queue from a review inbox (zen) or gh; optionally catches up via an observational memory layer if one is connected; posts nothing without explicit per-PR authorization.

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. Different from `self-audit` (which reviews PR code). This audits how the user works with agents. Designed to be dispatched as a sub-agent so the caller's context stays clean.

Self-contained playbook for rigorous PR review. Use when starting a PR review and you want the full discipline: state inspection, design-intent hunting, four verification rules (cite primary sources, walk commits forward, investigate-not- ask, verify actual artifacts), agent dispatch, falsifiable-matrix output format, and GitHub posting only with explicit authorization. Generic — not tied to any specific repo, org, or PR author. Sequential phases; can be applied end-to-end or used as a reference for specific phases.

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.

Produce structured comparisons between a project being built (described by a baseline doc) and external systems that solve adjacent problems. Outputs follow this skill's TEMPLATE.md, cite primary sources for every claim, and update a cross-cutting matrix in the project's prior-art/README.md. Refuses to compare more than 5 systems per invocation. Refuses to assert without citation. Use when researching prior art, evaluating "are we reinventing X?", or building shoulders-of-giants context before committing to a substrate design.

Audit and polish the GitHub repository description — the one-sentence pitch shown in search results, link previews, and embeds. Proposes a stronger description from README + signals, applies via gh repo edit after user approval. Modular sub-skill of repo-seo-curator.

Audit and set the GitHub repository homepage URL — the link on the repo card's "About" panel and on every search result. Detects candidate URLs from docs sites, package registries, demos, and org homepages, then applies via gh repo edit after user approval. Modular sub-skill of repo-seo-curator.

Audit the GitHub OpenGraph social preview image — the card shown when a repo URL is posted on HN, Twitter, Slack, or Discord. Detects whether one is set, evaluates the existing image's clarity at small sizes, suggests sources for missing ones (existing logo, generated card), and reports the manual upload steps. Modular sub-skill of repo-seo-curator.

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. Modular sub-skill of repo-seo-curator.

Pre-review self-audit of a PR branch. Use after addressing review feedback, before tagging a human reviewer, or after a significant self-directed refactor. Runs a structured pass looking for the stuff a careful human reviewer will catch but a compiler won't — dead struct fields, rotting comments, duplicate types, test-only exports, scope drift — then dispatches an adversarial agent on the diff for deeper design flaws.

Decompose feature work into reviewable, shippable units before coding starts. Use when the user provides a ticket (Linear ID, GitHub issue), describes a feature to build, or is about to start a multi-file change. Breaks work into a sequence of PRs that each have a single clear purpose a reviewer can hold in their head. Feeds into writing-plans — each work unit becomes a plan.

Given a PR number or diff, synthesize spec-driven diagram, emergent diagram, and impact analysis into a structured insight: block for the reviewer. Shows what the PR proposes, what the code actually does, the gap between them, and blast radius of changed symbols. Output is local reviewer context — never posted to GitHub.

Generate a bottom-up community diagram from real code cross-references. Shows emergent coupling structure — what the code actually does, not what was intended. For structural PRs, output may be included in the GitHub review body. Pair with diagram-gen-spec to see intended vs actual drift.

Generate a top-down structural diagram from a mache schema file. Shows intended architecture — what the PR proposes, not what the code does. Reviewer local context only, never posted to GitHub. Pair with diagram-gen-emergent to see spec vs reality drift.

Give or respond to PR reviews with structural awareness via mache. Review mode: runs review-prep (spec-driven + emergent diagrams + impact analysis), shows reviewer the structural picture locally, then runs parallel analysis agents with enriched prompts, synthesizes into one GitHub review submission (body + inline comments). Mermaid diagrams shown locally before posting. Respond mode: addresses reviewer comments.

Start or locate a running mache MCP server for a source path or .db file. Builds a .db from source if needed. Base skill used by diagram-gen-spec, diagram-gen-emergent, and review-prep. Returns port and session ID.

Multi-perspective codebase survey that produces beads and mermaid diagrams from code structure. Each agent perspective (prod, staging, dev, feature, PM) examines the same codebase at a different zoom level, creating tagged beads and a disagreement matrix.

Research-first feature implementation workflow. Use when building new features, services, or any net-new code that should follow existing codebase patterns. Enforces pattern discovery before coding to prevent duplication, convention violations, and infrastructure conflicts. Language-agnostic; dispatches to repo-specific standards skills for convention checks.

Emergency IAM elevation for oncall/debugging. Discovers GCP projects and guides through granting/revoking permissions.