repo-engineering

Recover architecture decisions that were made but never written down by mining git history, manifest and config changes and rationale comments, then draft MADR stubs (status proposed) that cite a commit SHA on every line; a second script lints an existing docs/adr folder for numbering, status and superseded-link problems. Use when asked "why did we switch to X?" or to backfill ADRs. Not for recording a decision being made now (adr-writer, or decision-log for operational decisions) or generating a changelog.

Write or refresh AGENTS.md and CLAUDE.md so they hold only what an agent cannot learn from the code, and lint them for lines that restate manifests, scripts, dependency lists or directory trees, paths that do not exist, generic advice and length over a budget. Use when asked to "shorten our CLAUDE.md", after /init produced a long file, or when agents ignore a bloated context file. Not for auditing agent permissions, hooks or MCP configuration (agent-config-audit), or human onboarding docs.

Audit a whole repository against a fixed checklist (structure, entry points, dependency hygiene, dead code, test coverage, secrets and config, CI health) where every finding cites a path:line with a quoted snippet, and a bundled validator rejects findings whose citation does not resolve. Use when asked to "audit this codebase", to assess tech debt, or for technical due diligence before taking over or acquiring a codebase. Not for reviewing a single diff, vulnerability scanning, or performance profiling.

Verify that a repository's README, docs/, AGENTS.md and CLAUDE.md still match the code, checking file paths, links, CLI flags and defaults, environment variables, symbol names, config keys, npm and make targets and version strings against the working tree. Use when asked "is the README out of date?", after renaming files, flags or functions, before a release, or to add a docs drift gate to CI. Not for judging prose quality or rewriting docs (readme-who-what-why), or checking external URLs.

Stress-test an implementation plan before anyone writes code: put a fixed set of questions to the author (scope, interfaces, data, failure modes, rollout, tests, open questions), fold the answers into the plan, then run a bundled script that checks the Markdown for the required sections, placeholders, a missing rollback and questions with no owner or answer, listing each gap with its line. Use when asked to "grill this plan" or before approving a design for implementation. Not for tracking a proposal's status over time (rfc-lifecycle in ways-of-working-skills).

Check whether a README's first screen answers six questions (what it is, who it is for, why it exists, how to install, one example, where to ask), flag hype words, list the gaps as a to-do list, then fix them with verified text. Use when asked to "review my README", before publishing or announcing a repository, or to add a README gate to CI. Not for checking whether README commands still work (docs-truth-check), writing a README from scratch (readme-author), or long-form documentation.

Check a release's notes against what changed between two tags, flagging notes that match no commit, commits with no note (chores excluded by a pattern), manifest versions that disagree with the tag, and missing compare links; pull request titles are read only when asked. Use when asked "are the release notes complete?", before tagging, or as a release CI gate. Not for drafting notes from commits (release-notes), semantic version policy, or detecting breaking API changes.

Run one offline hygiene pass over a repository and report findings with severity as a table, JSON or SARIF with a CI exit code, covering manifests without lockfiles, lockfile drift, version splits across workspaces, missing licence or SPDX fields, redacted secret-shaped strings, actions pinned by tag, write-all workflows, missing SECURITY.md, and large or built files. Use when asked "is this repository ready to open source?" or to add a hygiene gate to CI. Not for vulnerability scanning, secret search through history, or licence compatibility audits.

Write an onboarding guide for a repository (how to run and test it, where things live, which services it needs, who owns what) only from facts a bundled script extracted with a path:line citation each, then lint the guide so every command, path, variable, service or owner matches a fact. Use when asked "how do I get started in this repo?" or to write or refresh an onboarding doc for a new hire. Not for diagrams, API reference docs, or a README's first screen (readme-who-what-why).

Plan a repository restructure (split or merge packages, fix module boundaries) from the real import dependency graph of Python, JavaScript and TypeScript files, reporting the most coupled files, import cycles and god modules, and proposing a move plan with blast radius and git mv commands it prints and never runs. Use when asked "how should we split this package?" or to break an import cycle before a large refactor. Not for renaming symbols, build or bundler analysis, or other languages.

Clean up a repository's branch list safely: a bundled script joins saved gh and git exports (the remote's branches, for-each-ref dates and committers, merged refs, pull requests) and reports merged branches never deleted, branches idle for N days, branches with an open PR and protected ones, with the last committer as owner, then writes the exact git push --delete commands as a list to review and never runs them. Use when asked "which branches can we delete?" or before archiving a repository. Not for a whole-repository hygiene pass (repo-hygiene-bundle).

Find public functions, classes and CLI entry points that no test mentions in Python, JavaScript and TypeScript code, rank them (entry points first, then size and fan-in), and write characterisation test stubs in the project's framework. Use when asked "what is untested?", where to add tests first, or to pin behaviour before a refactor. Not for measuring coverage (it never runs tests), module-level gap lists or coverage ratchets (test-gap-finder).