agentleFS
converge-ai-labsconverge-ai-labs/agent-foundation/.agents/skills/audit-repository-consistency/SKILL.md

audit-repository-consistency

Skill1.3k starsChanged 4 days agoApache-2.0View on GitHub

Audit a repository or revision range for spec-code gaps, inconsistent shared concepts, semantic duplication, and removable code. Use for repository consistency or architecture-conformance reviews; report evidence-backed findings and remediate only when requested.

Adopted by

Steady: 0 new projects took it in the last 4 weeks, none the 4 weeks before.thin data

Week of Sep 20: 0 new projectsWeek of Sep 27: 0 new projectsWeek of Oct 4: 0 new projectsWeek of Oct 11: 0 new projectsWeek of Oct 18: 0 new projectsWeek of Oct 25: 0 new projectsWeek of Nov 1: 0 new projectsWeek of Nov 8: 0 new projects
Sep 2026Oct 2026Nov 2026
New projects taking a version of this file each week, over the 8 weeks our latest run read: only 0 in all, so this is a hint, not a trend.

Who's talking about converge-ai-labs/agent-foundation

The biggest 5 of 50 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 50

Talked about on GitHub (50 times).

On GitHub · 50

45 more on GitHub

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 4 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Follow the repository's AGENTS.md and contribution rules.

    line 12
  2. Very specific:

    Default to the current worktree, including staged, unstaged, and relevant untracked changes.

    line 20
  3. Distinctive:

    Ask a focused question only if unresolved topology, missing refs, or multiple plausible targets/bases would materially change coverage.

    line 24
  4. Distinctive:

    Follow each material concept through applicable stages:

    line 34
  5. Distinctive:

    Look for competing policies or representations of IDs, pagination, time, versions, errors, state transitions, configuration, schemas, …

    line 53
  6. Very specific:

    Check unreachable or ineffective paths, orphaned registrations/assets/jobs, unused dependencies, expired flags, superseded helpers, and …

    line 59
  7. Distinctive:

    Before calling anything removable, verify:

    line 61

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Repository Consistency Audit

Determine whether accepted contracts match actual behavior, shared concepts have consistent owners, and retained implementation paths still serve a purpose. Prefer consequential, proven findings over search matches.

Scope and Evidence

Follow the repository's AGENTS.md and contribution rules. Read the engineering standards and owning specification sections for the surfaces under review; use spec/README.md to locate owners. Reuse documents already read.

Keep audits read-only unless remediation is requested. Accepted specifications define intended behavior; code and tests establish actual behavior. Do not copy implementation drift into a specification to make the mismatch disappear. Private implementation details need a specification only when they affect observable behavior, ownership, security, or compatibility.

Resolve the Audit Basis

Identify the target snapshot, optional baseline, and requested surfaces before analysis:

  • Default to the current worktree, including staged, unstaged, and relevant untracked changes. Record the full HEAD ID and whether local changes are included. An explicit revision or HEAD request excludes local changes.
  • A whole-project or full request has no baseline. A request limited to a feature, directory, or file stays within that scope, including directly affected owners and consumers.
  • For a branch or change review without an explicit base, inspect Git status, the repository default/integration branch, merge base, and diff summary. Use the meaningful base found there and state the choice; a tracking ref that merely mirrors the feature branch is not a useful base.
  • Resolve supplied revisions to full commit IDs. Interpret “against a branch/ref” as its merge base with the target unless an exact snapshot comparison is requested. Use an explicit ancestor commit directly.
  • Ask a focused question only if unresolved topology, missing refs, or multiple plausible targets/bases would materially change coverage. For a non-ancestor explicit commit without comparison semantics, clarify exact comparison versus merge base.

State the resolved basis and proceed when the request and Git evidence establish it. Do not require confirmation just because a default was used, and do not infer a previous audit or maintain checkpoints.

Trace the Relevant System

Inventory with rg --files or git ls-files; locate owning specs, public entry points, schemas, persistence, generators, tests, and automation. Mark generated, vendored, fixture, cache, and migration-history paths so they are assessed through their owners.

For incremental reviews, read the aggregate diff with renames/deletions, then relevant commits when intent is unclear. Extract changed concepts and trace affected consumers beyond changed lines. For a full audit, start with specification indexes, public and durable boundaries, and shared infrastructure.

Follow each material concept through applicable stages:

specification -> definition/generation -> validation/persistence
              -> transport/SDK/UI -> observability/tests

Batch related searches and deep-read plausible owning paths. Use existing non-mutating checks to test candidates; do not install audit-only dependencies without authorization.

Audit Passes

Specification and implementation

Trace both directions: accepted entities, operations, defaults, states, authority, compatibility, and failure rules into code; public or durable behavior back to its owning contract. Compare semantics, including ordering, cancellation, retries, completion, and unknown outcomes.

Classify gaps as stale specification, implementation drift, incomplete implementation, missing accepted contract, intentional private detail, or unresolved design. Establish which authority should change before recommending remediation.

Consistency and duplication

Look for competing policies or representations of IDs, pagination, time, versions, errors, state transitions, configuration, schemas, authorization, transactions, logging, and redaction.

Recommend a canonical owner when definitions encode the same policy and must evolve together. Preserve deliberate isolation across packages, releases, languages, runtimes, and security boundaries. Boundary adapters, compatibility layers, and defense-in-depth checks may legitimately repeat logic; a few similar lines do not justify an abstraction. Prefer generation over runtime coupling for shared cross-language wire contracts.

Invalid and removable code

Check unreachable or ineffective paths, orphaned registrations/assets/jobs, unused dependencies, expired flags, superseded helpers, and completed cutovers.

Before calling anything removable, verify:

  1. Static references, aliases, exports, and string keys.
  2. Registries, decorators, reflection, dynamic imports, plugin discovery, and import side effects.
  3. CLI, environment, deployment, scheduled, serialization, persistence, and external entry points.
  4. Generators, manifests, packaging, builds, and release automation.
  5. Deprecation promises, old clients, compatibility layers, and migration history.

Classify candidates as confirmed removable, redundant and consolidatable, obsolete but compatibility-bound, or unproven. Age, missing tests, TODOs, and zero-result searches are not removal proof.

Validate and Report

For each candidate, read its complete owning contract and implementation path, trace alternate and cross-language consumers, and inspect relevant tests. Try to falsify it by looking for intentional isolation or compatibility requirements. Run the narrowest useful non-mutating checks; for review-only work, avoid formatting gates that rewrite the worktree.

Report actionable findings by severity, with a short statement of target/full commit ID, baseline/full commit ID or full audit, and worktree scope. Give each finding:

  • A stable ID, category, severity, and confidence.
  • Exact specification and implementation evidence with file paths and lines.
  • Actual versus required behavior and a concrete consequence.
  • The responsible owner and smallest coherent fix.
  • Removal proof, compatibility constraints, or unresolved decisions where relevant.

Include commands/results and coverage limitations. Keep unproven concerns separate from defects; never claim full coverage from sampling. If no actionable findings remain, say what was examined.

When fixes are requested, implement supported remediations and relevant tests. Use the repository's spec-writing skill for accepted specification changes. An unresolved design decision blocks only the affected remediation; continue independent authorized work. GitHub posting and other external mutations remain subject to the user's authorization.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.