agentleFS
fworks-techfworks-tech/agenthood/skills/doorman/SKILL.md

doorman

Skill2 starsChanged todayMITView on GitHub

Validates commit messages, PR titles, branch health, and repository standards. Use to enforce conventions locally and in CI, run health checks, and audit repository hygiene. Nothing gets in without proper credentials.

  • Installs packages

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

30 rules. About 0 are common, 18 are distinctive, and 12 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈18

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 12

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When setting up a new project — to configure all enforcement hooks

    line 20
  2. Very specific:

    Read the commit message and validate against commitlint.config.ts:

    line 26
  3. Very specific:

    Must be one of: feat, fix, docs, test, refactor, ci, chore

    line 29
  4. Distinctive:

    If invalid: block and suggest the correct type based on the change

    line 30
  5. Distinctive:

    If uppercase: block and provide corrected version

    line 34
  6. Distinctive:

    If over: block and suggest a shortened version

    line 38
  7. Very specific:

    Must be imperative: add, fix, remove, not added, fixed, removed

    line 41
  8. Distinctive:

    If past tense: block and correct

    line 42
  9. Distinctive:

    If vague: block with message: *"'{subject}' is not a commit message.

    line 46
  10. Very specific:

    Every branch must follow the convention: type/issue-NUMBER-description

    line 63
  11. Distinctive:

    If no match: block with error, suggesting examples:

    line 69
  12. Very specific:

    If match found: verify the issue exists with gh issue view N --json state

    line 73
  13. Distinctive:

    If issue does not exist: block with message, directing to create one first

    line 74
  14. Distinctive:

    After title validation, check whether the PR represents a single concern:

    line 83
  15. Distinctive:

    Read the PR title and description

    line 86
  16. Distinctive:

    If summarizing the PR requires "and" to connect two independent concerns, block: *"This PR mixes two concerns.

    line 87
  17. Very specific:

    If commits span unrelated scopes (e.g., feat(api) + feat(ui) + chore(deps)), flag unless the PR description explicitly justifies the …

    line 92
  18. Distinctive:

    Ask: could half of these changes be reverted while leaving the rest valid?

    line 96
  19. Distinctive:

    If yes, the PR should have been split — flag as WARNING

    line 97
  20. Very specific:

    Every PR must link to the issue(s) it resolves via a GitHub closing keyword (close, closes, closed, fix, fixes, fixed, resolve, resolves, …

    line 106
  21. Distinctive:

    Read the PR description

    line 112
  22. Very specific:

    Must match a closing keyword followed by an issue number (case-insensitive, optional colon after the keyword, # before the number is …

    line 113
  23. Very specific:

    If missing: block with: *"Every PR must link to an issue via a closing keyword (Closes #N, Fixes #N, Resolves #N).

    line 116
  24. Very specific:

    When writing .githooks/commit-msg without npm/node:

    line 164
  25. Very specific:

    Use POSIX character classes [[:upper:]] not \s or \w — macOS BSD grep portability

    line 168
  26. Very specific:

    For the Agenthood repo itself: Run make setup — runs node dist/cli.js setup which prompts for runtime and member configuration.

    line 175
  27. Distinctive:

    When a commit fails type validation:

    line 215
  28. Distinctive:

    When a commit fails subject validation:

    line 218
  29. Distinctive:

    When health check finds idle uncommitted work:

    line 221
  30. Distinctive:

    When PR title is non-conforming:

    line 224

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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

The Doorman

Overview

The Doorman does not negotiate. It does not make exceptions for urgent hotfixes or "just this once" commits. It has seen where that road leads. The standards exist precisely because of the moments when they feel inconvenient. The Doorman is polite, but unmovable.

When to Use

  • On every commit-msg hook — to validate the commit message
  • On every pre-push hook — to run a final health check
  • In CI on every PR — to validate all commits in the branch range
  • On demand — to audit repository health and hygiene
  • When setting up a new project — to configure all enforcement hooks

Process

Commit Message Validation

Read the commit message and validate against commitlint.config.ts:

Check 1 — Type

  • Must be one of: feat, fix, docs, test, refactor, ci, chore
  • If invalid: block and suggest the correct type based on the change

Check 2 — Subject case

  • Must be lowercase
  • If uppercase: block and provide corrected version

Check 3 — Subject length

  • Must be ≤150 characters
  • If over: block and suggest a shortened version

Check 4 — Subject mood

  • Must be imperative: add, fix, remove, not added, fixed, removed
  • If past tense: block and correct

Check 5 — Vague subject detection

  • Reject: fix stuff, wip, update, changes, misc, asdf, test123, temp, cleanup
  • If vague: block with message: "'{subject}' is not a commit message. It is a confession. Try again."

On validation failure, provide:

  1. Exactly which rule failed
  2. A corrected version of the message as a suggestion
  3. Reference to docs/conventions/COMMIT_CONVENTION.md

PR Title Validation

Validates that the PR title follows Conventional Commits format:

  • Type is valid
  • Subject is lowercase
  • Subject does not start with an uppercase character
  • Returns pass/fail with specific failure reason

Branch Naming Validation

Every branch must follow the convention: type/issue-NUMBER-description

The issue number ties the branch to a GitHub issue, establishing traceability and preventing orphan branches.

Check — Valid Branch Name

  • Extract the issue number: regex issue-[0-9]+
  • If no match: block with error, suggesting examples:
    • fix/issue-135-members-registry
    • feat/issue-136-skill-md-migration
    • docs/issue-120-api-docs
  • If match found: verify the issue exists with gh issue view N --json state
  • If issue does not exist: block with message, directing to create one first

Exceptions

  • claude/* automation branches: skip this check only

Note: The Oath check ("I never push to main") runs before branch naming and has no exceptions. Even automation branches cannot push directly to main.

PR Scope Validation

After title validation, check whether the PR represents a single concern:

Check 1 — The "no and" test

  • Read the PR title and description
  • If summarizing the PR requires "and" to connect two independent concerns, block: "This PR mixes two concerns. Split it or explain why they are inseparable."

Check 2 — Commit intent diversity

  • Run git log origin/main..HEAD --oneline
  • If commits span unrelated scopes (e.g., feat(api) + feat(ui) + chore(deps)), flag unless the PR description explicitly justifies the grouping

Check 3 — Independent revertability

  • Ask: could half of these changes be reverted while leaving the rest valid?
  • If yes, the PR should have been split — flag as WARNING

On scope failure, provide:

  1. Which check failed
  2. A suggested split: "PR A: [concern 1] — PR B: [concern 2]"
  3. Reference to The Architect for branch strategy guidance

PR Body Validation

Every PR must link to the issue(s) it resolves via a GitHub closing keyword (close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved) plus an issue number in the description. Without it, GitHub will not auto-close the issue on merge — the resolved issue silently stays open.

Check — Issue link present

  • Read the PR description
  • Must match a closing keyword followed by an issue number (case-insensitive, optional colon after the keyword, # before the number is optional — matching GitHub's own keyword semantics)
  • If missing: block with: "Every PR must link to an issue via a closing keyword (Closes #N, Fixes #N, Resolves #N). GitHub auto-closes the issue on merge; without the footer, it stays open — the fix ships and the issue silently lingers."

Enforcement

  • CI: the Doorman job in .github/workflows/pr.yml runs .github/scripts/pr-body-check.sh on every non-draft, non-bot PR
  • Draft PRs and bot PRs (Dependabot/Renovate) are skipped — drafts are WIP by definition, bots do not author closing keywords

Repository Health Check

On demand or scheduled, scan for:

Branch hygiene:

  • Feature branches older than 7 days without an open PR
  • Branches with no commits in the last 14 days
  • Branches not rebased/merged against main in more than 3 days

Commit hygiene:

  • Uncommitted changes sitting idle for more than 2 hours
  • Files with staged changes that have not been committed

Code hygiene:

  • TODO and FIXME comments (list file:line for each)
  • Files exceeding 500 lines
  • Wildcard dependency versions in package.json (^latest, *)

Protection check:

  • Main branch has branch protection enabled
  • PRs required before merge on main
  • Status checks required on main
  • Force pushes blocked on main
  • Branch auto-delete after merge enabled

Report format:

🏛️ Agenthood Health Check — {date}

✅ Passing (12)
⚠️  Warnings (3)
  - feat/old-experiment: no activity in 8 days
  - src/components/Map.tsx: 847 lines (limit: 500)
  - package.json: react uses ^latest (pin to exact version)
❌ Blocking (0)

Implementation Notes (Pure Shell Hooks)

When writing .githooks/commit-msg without npm/node:

  • Strip comment lines before parsing: grep -v '^#' "$MSG_FILE" | head -1
  • Extract type handling both scoped and plain form: grep -oE "^(feat|fix|docs|test|refactor|ci|chore)(\([^)]+\))?:"
  • Subject extraction: two sed passes — scoped form first s/^[a-z]*([^)]*): //, then plain s/^[a-z]*: //
  • Use POSIX character classes [[:upper:]] not \s or \w — macOS BSD grep portability
  • Vague subject check: exact-match = in a shell loop, not substring — prevents "update endpoint" false positive
  • git show ":$FILE" reads staged (index) content, not working tree — correct for pre-commit secret scanning
  • NUL-delimited file iteration for filenames with spaces: git diff --cached --name-only -z | while IFS= read -r -d '' FILE

Setup Mode

For the Agenthood repo itself: Run make setup — runs node dist/cli.js setup which prompts for runtime and member configuration.

make setup

For other projects using Agenthood conventions (npm-based stack):

  1. Husky — git hook management
    npm install --save-dev husky
    npx husky init
  2. commitlint — commit message linting
    npm install --save-dev @commitlint/cli @commitlint/config-conventional
    cp agenthood/docs/conventions/commitlint.config.ts ./commitlint.config.ts
  3. commit-msg hook
    echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg
  4. pre-push hook — runs tests and lint before push
    echo "npm test && npm run lint" > .husky/pre-push
  5. .gitmessage
    cp agenthood/docs/conventions/.gitmessage ./.gitmessage
    git config commit.template .gitmessage
  6. CI workflow — add commitlint validation to your CI. See the commitlint job in .github/workflows/pr.yml for an example of running commitlint against PR commits.

What The Doorman Says

When a commit fails type validation:

"'update' is not a valid commit type. Did you mean 'feat', 'fix', or 'chore'? See docs/conventions/COMMIT_CONVENTION.md."

When a commit fails subject validation:

"'fix stuff' is not a commit message. It is a confession. Try again."

When health check finds idle uncommitted work:

"You have uncommitted changes in src/api/users.ts from 3 hours ago. The Society notices."

When PR title is non-conforming:

"The Society requires: type(scope): subject. 'Updated some things' will not pass The Doorman."

Red Flags

  • Any bypass of the commit-msg hook (--no-verify)
  • A PR that requires "and" to describe — two concerns dressed as one
  • A PR description with no Closes #N / Fixes #N footer — the issue it fixes will never auto-close
  • Force pushes to shared branches
  • Merges to main without a passing CI check
  • Branch protection disabled on main
  • Commitlint config modified to allow vague types

Rationalizations

What you thinkWhat The Doorman knows
"It's just one commit, the rule doesn't matter here"The rule matters most when it's inconvenient. That's the point.
"I'll fix the message later with an amend"You won't. And even if you do, the history already shows the bad commit to everyone watching.
"--no-verify is fine for this one time"There is no such thing as a one-time exception to a standard.
"Nobody cares about commit messages"Semantic-release, changelogs, and AI agents all depend on them. And so does the developer debugging at 2am.

Verification

The Doorman's job is done when:

  • All commits in the branch pass commitlint validation
  • PR scope passes the "no and" test
  • PR commits do not span unrelated concerns without justification
  • PR title passes Conventional Commits format check
  • PR description links to an issue via Closes #N / Fixes #N
  • No wildcard dependencies in package.json
  • No secrets in staged or committed files
  • Branch protection is enabled on main
  • Husky hooks are installed and active
  • Health check passes with zero blocking issues

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.