agentleFS
EricSanchezokEricSanchezok/repo-seed/.agents/skills/repo-governance/SKILL.md

repo-governance

Skill10 starsChanged 32 days agoMITView on GitHub

Use when repository complexity, delivery, ownership, security, release, or incident signals change; when governance may be missing; or when adding, reviewing, deferring, or upgrading repo-seed capabilities

The file

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

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

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

    Run node scripts/audit-governance.mjs --json and read .repo-seed/manifest.json.

    line 12
  2. Very specific:

    Check whether a recommendation's observed facts and safety boundary actually apply to the current change.

    line 14
  3. Distinctive:

    Check whether an existing or external mechanism already satisfies the need.

    line 34
  4. Very specific:

    Ask for authorization. Record enabled, external, deferred, or declined plus the assessment hash and concise reason.

    line 36
  5. Distinctive:

    Update review instructions when the capability adds a new risk surface.

    line 38
  6. Distinctive:

    Do not convert every preference into a gate.

    line 49
  7. Very specific:

    When .repo-seed/manifest.json is absent, a read-only audit and adoption proposal are allowed.

    line 53

≈ “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

Evolving repository governance

Governance grows with the repository. Do not install every mechanism up front, and do not wait for a preventable failure before naming a new control.

Start with a read-only assessment

Run node scripts/audit-governance.mjs --json and read .repo-seed/manifest.json. The audit observes discrete repository facts only; it does not authorize changes.

  • Check whether a recommendation's observed facts and safety boundary actually apply to the current change. A blocking label alone does not make an optional capability a task-wide gate; a confirmed safety dependency blocks only the affected action.
  • An advisory recommendation improves maturity without making the current work unsafe. Finish the requested work, then raise it in the handoff.
  • A suppressed recommendation was already declined or deferred against the same facts. Do not ask again until its assessment hash changes.

Missing optional tools or unavailable external evidence do not block independent authorized work. Reuse valid evidence, bound retries, and report the exact unresolved dependency. Do not repeat approval already given for the same scope.

Authority boundary

You may autonomously inspect, audit, compare capability state, and produce a dry-run. Ask the user before you:

  • enable a capability or add its files;
  • install or replace a Git hook;
  • change governance policy or a source of truth;
  • connect an external system or change remote permissions.

Once a capability is enabled, untouched repo-seed-owned files may refresh through the normal upgrade channel. Preserve user-owned content and stop on conflicts.

Midstream capability workflow

  1. Name the new repository facts and the capability they make relevant.
  2. Check whether an existing or external mechanism already satisfies the need.
  3. Explain benefit, ongoing cost, files/processes added, and whether the recommendation blocks current work.
  4. Ask for authorization. Record enabled, external, deferred, or declined plus the assessment hash and concise reason.
  5. Preview with a dry-run, apply only the approved capability, then run node scripts/run-gates.mjs.
  6. Update review instructions when the capability adds a new risk surface.

Promotion ladder

Promote knowledge to the cheapest layer that reliably prevents recurrence:

  • one task-specific fact stays in its spec or plan;
  • a repeated project convention becomes resident instruction or a focused skill;
  • a rule that must hold without exception becomes a deterministic gate;
  • a systemic escaped failure becomes a postmortem linked to the new guardrail.

Do not convert every preference into a gate. Deterministic enforcement is for objective rules with low false-positive cost.

Unmanaged repositories

When .repo-seed/manifest.json is absent, a read-only audit and adoption proposal are allowed. Never write the Core automatically. The adoption sequence is audit, dry-run, user authorization, incremental write, then verification. Preserve an existing source of truth rather than creating a duplicate.

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.