124 lines
5.9 KiB
Markdown
124 lines
5.9 KiB
Markdown
---
|
|
name: repo-maintainer
|
|
description: "Audit and repair repository hygiene across artifacts, dependencies, CI, docs, Git state, and code-quality signals. Use for repository maintenance, cleanup, health checks, or pre-release hardening."
|
|
risk: critical
|
|
source: https://github.com/Wolfe-Jam/faf-skills/tree/main/skills/repo-maintainer
|
|
source_repo: Wolfe-Jam/faf-skills
|
|
source_type: community
|
|
date_added: 2026-07-01
|
|
license: MIT
|
|
license_source: https://github.com/Wolfe-Jam/faf-skills/blob/main/LICENSE
|
|
---
|
|
|
|
# Repository Maintainer
|
|
|
|
## Overview
|
|
|
|
Audit repository health, apply authorized repairs narrowly, and finish through the repository's own protected workflow.
|
|
|
|
## When to Use
|
|
|
|
Use when the user asks to maintain, clean, audit, harden, or prepare a repository for release. Use a more specific security, database, deployment, or release skill when that is the dominant task.
|
|
|
|
## Repository Policy Gate
|
|
|
|
Before mutation:
|
|
|
|
1. Read root and nested `AGENTS.md`, contributor guidance, maintainer docs, and release instructions.
|
|
2. Inspect the current branch, worktree, staged files, remotes, default branch, and effective branch protection.
|
|
3. Discover repository-native validation, synchronization, merge, and release commands.
|
|
4. Preserve unrelated user work and generated outputs that are not in scope.
|
|
|
|
If the repository names a mandatory maintainer skill or guarded command, delegate to it instead of inventing a parallel branch, merge, sync, or release path. In `agentic-awesome-skills`, use `antigravity-maintainer-batch-release` and `npm run merge:batch`; `main` is pull-request-only.
|
|
|
|
The routine protected checks for `agentic-awesome-skills` are `pr-policy`, `pr-evidence`, `source-validation`, and `artifact-preview`. The supported AAS Core preview uses targeted unit tests plus one packed Linux/Node LTS smoke path and Workbench review. Do not resurrect the retired certified-v1 baseline, benchmark, tuning-gold, transaction-fault, race, or frozen OS/runtime matrix as routine merge gates.
|
|
|
|
## Usage
|
|
|
|
### 1. Establish the baseline
|
|
|
|
```bash
|
|
git status --short --branch
|
|
git diff --stat
|
|
git diff --cached --stat
|
|
git remote -v
|
|
git log -5 --oneline
|
|
```
|
|
|
|
Record the repository's required runtime versions and test commands. Use a clean temporary clone or worktree when existing user changes cannot be isolated safely.
|
|
|
|
### 2. Audit independent lanes
|
|
|
|
Run independent read-only checks in parallel where possible.
|
|
|
|
#### Artifacts and Git hygiene
|
|
|
|
- untracked caches, coverage, build output, editor files, and test leftovers;
|
|
- tracked large or binary files, accidental secrets, executable-mode drift, and ignored-file gaps;
|
|
- stale branches, detached HEAD, existing staged changes, submodules, and symlinks;
|
|
- generated files whose ownership belongs to CI or a canonical-sync workflow.
|
|
|
|
Do not delete or rewrite history during the audit.
|
|
|
|
#### Dependencies and packaging
|
|
|
|
- lockfile and manifest agreement;
|
|
- outdated, vulnerable, duplicate, unused, or end-of-life dependencies;
|
|
- runtime imports incorrectly placed in development dependencies;
|
|
- clean-install, package-content, and executable-entrypoint behavior.
|
|
|
|
Treat audit-tool output as evidence to verify, not automatic permission to upgrade or remove packages.
|
|
|
|
#### CI and release health
|
|
|
|
- failing, cancelled, skipped, or stale workflow runs;
|
|
- stale, redundant, or unjustifiably broad runtime matrices and unpinned or obsolete actions;
|
|
- required checks, branch protection, release permissions, and secret boundaries;
|
|
- mismatch between documented and implemented release commands.
|
|
|
|
#### Documentation and repository metadata
|
|
|
|
- README, changelog, version, examples, links, badges, credits, and support metadata;
|
|
- contribution instructions and PR templates versus current CI policy;
|
|
- generated catalog, site, or API documentation drift.
|
|
|
|
#### Code-quality signals
|
|
|
|
- dead code, stale implementation markers, debug logging, commented-out code, and missing tests;
|
|
- unsafe defaults, suppressed errors, credential exposure, and environment-specific paths.
|
|
|
|
For FAF projects only, also inspect declared `.faf`, `.faf-dna`, sync, score, and MCP contracts with the project's installed FAF commands.
|
|
|
|
### 3. Produce a prioritized decision set
|
|
|
|
For each finding report:
|
|
|
|
- evidence and affected paths;
|
|
- severity and user impact;
|
|
- whether it is safe to fix now, needs approval, or belongs to another workflow;
|
|
- exact validation that proves the repair.
|
|
|
|
Deduplicate symptoms with the same root cause. Do not mix optional modernization with release blockers.
|
|
|
|
### 4. Apply authorized repairs
|
|
|
|
Make the smallest coherent change set. Keep source and generated-file ownership separate, update tests with behavior changes, and rerun the targeted failing check after each repair group.
|
|
|
|
Never delete data, rewrite history, rotate credentials, change branch protection, or upgrade across breaking versions without explicit authorization.
|
|
|
|
### 5. Validate and publish safely
|
|
|
|
Run the repository's required pre-PR suite, then inspect the final diff for unrelated files and secrets. Commit on a topic branch and create a pull request when the target branch is protected.
|
|
|
|
Use required checks and the repository-native merge path. A user request to “push to main” describes the desired final state; it does not bypass branch protection. For releases, use the scripted release workflow and verify external publication rather than inferring success from a local tag.
|
|
|
|
## Stop Condition
|
|
|
|
Finish when every in-scope finding is repaired or has one exact blocker, required validation passes, the remote integration path is verified when requested, and unrelated user work remains unchanged.
|
|
|
|
## Limitations
|
|
|
|
- Maintenance findings can depend on repository-specific ownership and release policy; read local instructions before acting.
|
|
- Dependency and security scanners can produce false positives or incomplete reachability evidence.
|
|
- This skill does not authorize destructive cleanup, branch-policy changes, direct protected-branch pushes, merges, deployments, or releases beyond the user's request.
|