maintainerd

Execute one tick of the autonomous issue-to-PR pipeline — triage open issues for readiness, draft plans for maintainer approval, build the oldest approved issue into a PR, address review feedback; never merges; state lives in configurable auto:* GitHub labels. Designed to run as a recurring scheduled task that invokes this skill directly each tick in a full-toolchain sandbox; also invocable interactively as "/auto-dev" or "run an auto-dev tick", and as "/auto-dev dry-run" for a read-only report of what a tick would do. The auto:* label names, comment marker, and branch prefix are configurable per repo via `.claude/maintainerd.json`.

The maintainer's daily console for the auto-dev pipeline — gather everything blocked on you, present a worklist, loop executing your decisions against the `auto:*` state machine as you (never with the bot marker), until the queue drains. Never merges on its own; never builds issues. Use when the user says "review the pipeline", "what needs my input", "process the auto-dev queue", "check what auto-dev is waiting on", "approve/answer/park

Generate the maintainerd config contract for a repo — write `.claude/maintainerd.json` and scaffold `.claude/guidelines/{coding,testing,invariants}.md` so the repo-ops, audits, research, and auto-dev skills can run here. Inspects the repo (language, GitHub slug, default branch, source/test dirs, lint/format/build/test commands), confirms anything ambiguous, and seeds starter guidelines from existing CLAUDE.md/AGENTS.md. Use when the user asks to "bootstrap this repo", "set up maintainerd", "create the maintainerd config", "configure the maintainer skills", "onboard this repo to maintainerd", or when any other maintainerd skill reports the config is missing. Idempotent — re-running re-confirms and only rewrites changed keys; never clobbers hand-edited guideline prose.

Validate a repo's Maintainerd setup and report what's wrong — the companion to `bootstrap`. Checks that `.claude/maintainerd.json` exists, parses, and conforms to the schema; that the configured paths, commands, and guidelines files resolve; that the GitHub labels the skills apply actually exist; that the daily-update roster only names installed skills; that the auto-dev state labels exist when the pipeline is enabled; and that release config is coherent. Read-only diagnosis by default, grouped PASS/WARN/FAIL with a concrete fix for each finding; offers to create missing labels and points at `/bootstrap` or the guidelines files for the rest. Use when the user asks to "run doctor", "check the maintainerd setup", "validate the config", "why isn't <skill> working", "diagnose the agent-skills config", or after onboarding a repo to confirm it's wired correctly.

Walk the repo's source in the configured language looking for technical debt — oversized files, DRY violations, dead code, missing tests, sloppy typing, weak abstractions, and drift against the repo's documented invariants. Categorize each finding into a discrete unit of work; open a focused PR for mechanically-safe fixes and file a GitHub issue for refactors that need design discussion. One PR or one issue per finding — never bundled. Use when the user asks to "audit the architecture", "find tech debt", "look for code smells", "do an architecture sweep", or when invoked nightly by a scheduled remote agent. Has working-tree side effects (branches + PRs) and GitHub side effects (issues, labels). Quiet-day result is "codebase looks good" with no PR or issue — that's a valid outcome.

Weekly scan of arXiv for papers relevant to the work in this repo — derive themes from the repo, query arXiv, curate the few most relevant papers, write a dated digest, and open a PR. Use when the user asks to "run the research radar", "scan arxiv", "find recent papers relevant to <repo>", "what should we read this week", or when invoked by the weekly scheduled remote agent.

Turn a rough request into a well-formed GitHub issue that's ready for the auto-dev pipeline. Takes the user's description, then either investigates the codebase to isolate the affected files, likely root cause, and repro — or asks targeted clarifying questions when the ask is underspecified — and drafts an issue with a crisp problem statement, acceptance criteria, and concrete file/symbol pointers. Dedups against existing issues, shows the draft for confirmation, files it, and labels it so auto-dev's triage can pick it up. Reads the repo config for the repo slug, source paths, and (when auto-dev is enabled) the pipeline labels. Use when the user wants to "create/file/open an issue", "turn this into an issue", "file a bug / feature request", or "write up an issue for X". Do NOT use to browse or triage existing issues, or when the user only wants an in-chat answer without filing anything.

Capture what was accomplished on a given day — drawn from the day's merged PRs (the complete picture, since work also happens in cloud sessions and other terminals) enriched by the live session (the why behind the slice it has context on) — and persist it to the user's Obsidian vault in three places: a session-summary note, a link from the project hub note, and a one-line entry in the daily note. User-scoped: reads the vault path from the user-level `~/.claude/maintainerd.json` (`journal.vault`) and an optional per-repo project pointer from the repo's `.claude/maintainerd.json`. Use when the user wants to "log this session", "write up a dev log / worklog", "journal what we did", "record this work in my vault", "log what shipped today", or similar — optionally with a project name, vault path, or date. Do NOT use for general note-taking unrelated to the work, for project docs/specs, or when the user just wants an in-chat summary without writing to the vault.

Cut a versioned release of the repo — gather every change since the last tag (not just this session), update the repo's release notes / changelog, run the pre-flight checks and the repo's final release gate, bump the version via the repo's configured mechanism, push the tag, create/publish the GitHub release, and verify. Reads `config.release` for the version-bump mechanism + notes file and `config.guidelines.release` for repo-specific gates and caveats. Use when the user asks to "cut a release", "ship a release", "bump the version", "publish a new version", or "do the release". For repos that ship continuously (no versioned releases) it confirms before doing anything.

Drive the iterative response loop on a PR you own — fetch every piece of review feedback (automated reviewers like CodeRabbit / gemini-code-assist AND human reviewers), triage it, fix the real issues with one focused commit each, run the repo's pre-flight, push, then post a reply to every thread (inline file:line replies plus a PR-level round summary) — because silence makes bots re-raise the same items and leaves humans unsure you saw them. Wait for the next round and repeat until the PR is approved. Reads the repo config for repo slug, default branch, and pre-flight commands. Use whenever the user wants to address, respond to, handle, work through, or iterate on review comments on their PR — "address the review feedback", "respond to the review on PR

Review design/architecture/planning docs, validate each claim against the code, fix drift, and add docs for uncovered load-bearing subsystems. Use when the user asks to "review planning docs", "audit the design docs", "validate docs against the code", "sync docs with the codebase", "find doc gaps", or similar. Covers DESIGN docs — the sibling `audit-product-docs` covers user-facing docs. Writes drift fixes + new docs to the working tree and stops; the caller (a human, or the `daily-update` meta-skill) is responsible for committing and opening a PR.

Validate the repo's user-facing / product / contributor docs against the code (settings/config names + defaults, command/action IDs, file paths, schedule/cron formats, tool/function names), patch drift in place, and add new docs only for user-visible features that aren't covered. Use when the user asks to "audit the docs", "review the docs", "validate docs against the code", "sync docs with the codebase", "find doc gaps", or similar. Covers USER-FACING docs — the sibling `audit-design-docs` skill covers internal design/architecture docs. Writes drift fixes + new docs to the working tree and stops; the caller (a human, or the `daily-update` meta-skill) is responsible for committing and opening a PR.

Review code for quality, correctness, and maintainability. Use this skill when reviewing pull requests, auditing existing code, refactoring for clarity, or enforcing coding standards. Covers DRY principles, SOLID design, error handling, performance, security, testing, and language-specific best practices. Reads the repo's coding and testing guidelines (config.guidelines.coding, config.guidelines.testing) so review feedback matches the standards this repo actually enforces, and follows any additional domain guidance the config points to.

Create a pull request for the current repository the right way — enforce the repo's PR template, run every CI gate (format, lint, build, typecheck, tests) locally before pushing, require docs updates for user-facing changes, and write an honest, non-marketing PR body. Use whenever the user wants to "create a PR", "open a pull request", "submit changes", "prepare changes for review", or "push this for review". Never bypasses verification, never auto-merges.

Generate a daily changelog / release-notes document from the PRs that merged on a given date and write it to `config.paths.changelogDir` as `YYYY-MM-DD.md`. Use when the user asks for "the daily changelog", "daily release notes", "release notes", "what shipped today/yesterday", "what landed on <date>", "write up today's changes", "summarize the day's PRs", or any variant of "what merged on <date>". Defaults to yesterday when no date is given. Always writes one markdown file per day.

Run the repo's per-day housekeeping skills and bundle their output into one PR. Each sub-skill writes to the working tree (or mutates GitHub directly); this skill runs the configured roster in sequence, collects what they wrote, and packages the combined diff into a single PR. Use when the user asks to "do the daily update", "run the daily skills", "morning sweep", "end-of-day cleanup", or when invoked by a scheduled remote agent doing the daily run. The roster is configured per-repo in `config.dailyUpdate.subSkills`. Bundles the per-day skills behind one entry point so a single schedule slot covers the whole routine. Safe to invoke manually at any time.