Skip to content

How it works

Agent skills maintain each ecosystem's repository, and nothing becomes an opinion until it passes CI and the maintainer's review, with another agent reviewing it first.

Each ecosystem has its own repository

An ecosystem's opinions, templates, skills, and source roster live in its own repository, and the website repository publishes them. When an ecosystem's main changes, it asks website to rebuild. A production build always uses every ecosystem's main, whichever repository triggered it. A pull request in an ecosystem builds a full-site preview from its own branch and every other ecosystem's main.

Suggestions from the site's issue forms move to the ecosystem they name. Two shared repositories serve every pull request: .github holds the attribution check, and coderabbit the review configuration.

RepositoriesBlock diagram of the awesome-humans repositories. Each ecosystem, such as dotnet and rust, holds its own opinions, skills, and roster. When its main changes, it dispatches to website, which checks out every ecosystem at main, runs its stage command, builds the site, and deploys awesome-humans.net. An ecosystem's pull request builds a preview through website's build. Readers' suggestions arrive through website's issue forms and move to the ecosystem as vet-source issues. The .github repository supplies the attribution check and coderabbit the review configuration for every repository's pull requests.contentpublishingthe siteawesome-humans/dotnetopinions, skills, the rosterawesome-humans/rustopinions, skills, the rosterone for each ecosystemin ecosystems.tomlawesome-humans/websitestages every ecosystem,then builds the site:theme, shared pages,issue intakerebuilds weekly toodispatch when main changeschecks out main, runs stagepull request: preview buildsuggestions, as vet-source issuesawesome-humans.netand a preview per PRdeploysReadersdevelopers and agentsreadsissue formssuggest, opt outawesome-humans/.githubattribution check, profile, PR templatesawesome-humans/coderabbitone review configuration for allevery repository's pull requests

Every change goes through a pull request

Each skill that changes a repository works on its own branch and opens a pull request. CI checks that:

  • Every opinion and template has valid metadata
  • Every cited source is on the roster and citable
  • Every link resolves

The agent reviewer (currently CodeRabbit) also checks the change, with the maintainer's agent answering each finding. Its review is advisory: the maintainer reviews and merges the pull request.

Three skills report findings and change nothing:

  • audit-freshness finds stale review dates and lagging version pins
  • review-opinions checks that the opinions and templates still agree with the pages they cite, and with each other
  • review-project grades an external codebase against the opinions
Maintenance pipelineSwimlane diagram of how an ecosystem's repository maintains itself: vet-source, research-topic, resolve-research, harvest-sources, the version refresh, and weave-house-opinion each work on their own branch, pass the CI checks, get an agent review, pass the maintainer's review, and land in the roster, research, or the opinions and templates; audit-freshness, review-opinions, and review-project only report. Their findings, the release watch, the harvest reminder, and the maintainer start the next run.lanepicks upskillagent checkshuman gatelands inSourcesResearchOpinionsReportscandidate source,or a change in standingvet-sourcevet/<source-id>CI checks,agent reviewcheck evidencea questionabout <topic>research-topicresearch/<topic>CI checks,agent reviewreviewtopic saved inresearch/resolve-researchresolve/<topic>CI checks,agent reviewapprove weavemonthly harvestreminder issueharvest-sourcesharvest/<date>CI checks,agent reviewreviewrelease-watch PR,or a newer pinversion refreshrefresh/<version>CI checks,agent reviewreviewHOUSE-OPINIONS.mdinbox entryweave-house-opinionhouse/<slug>CI checks,agent reviewconfirm wordingperiodic cadenceaudit-freshnessreport onlyno pull requestperiodic cadence,or before a refreshreview-opinionsreport onlyno pull requesta project pathor repository URLreview-projectreport onlyno pull requestAWESOME-HUMANS.mdthe rosterresearch/staged, unresolvedopinions/templates/distilled guidancea reportnever saved herefindingsWhat starts a runfindings, the release watch, the harvest reminder, youstarts the next skill

Sources need a track record

A source joins the roster on its track record: at least two years of sustained writing, with depth, accuracy, and an independent view.

A source goes on the watch list if it:

  • Has less than two years of sustained writing
  • Has been dormant for over a year, unless its writing clearly continues elsewhere

The watch list supplies leads, but its sources are never cited. A source is vetted again when it goes quiet, its writing weakens, or a blocker clears.

Two markings limit how an opinion can cite a roster source, and CI enforces both:

  • Corroborate: a long track record but thin depth. An opinion can cite the source, but every claim it supports also needs an unmarked source.
  • Discovery-only: an aggregator, such as a newsletter or a curated list of links. It's never cited, and an opinion cites the primary source it leads to instead.
Source standingFlow diagram: vet-source sorts a candidate source into citable, with two years of writing and all four criteria; the watch list, under two years or dormant; or declined. A citable source is unmarked, marked Corroborate and never the only citation on a claim, or marked Discovery-only and never cited. Citable and watch-listed sources go back through vet-source when they go dormant, drop in quality, or clear a blocker.Candidate sourceblog, docs, book, newslettervet-sourcecriteriaCitablequotable in opinions and templates, within its markingunmarkedmay support a claim alone**Corroborate.**cited, never as the only source on a claim**Discovery-only.**never cited, only followed to its primary sourceWatch listleads only, never citedDeclinedoff the roster, the decision loggedtwo years and all four criteriaunder two years, or dormantotherwisedormant, weakerblocker clearsre-vetted: standing is never permanent

Research is staged, never merged in place

A research topic saves the evidence on a subject in its own pull request. A second pull request then promotes it into the opinions and templates, or discards it, and deletes the topic. A partial promotion keeps the blocked remainder staged until vet-source clears its source.

Research lifecycleFlow diagram: research-topic opens a pull request that saves research/<topic>.md; resolve-research then promotes it into the opinions and templates, discards it, or promotes part of it, deleting the topic in the same pull request. A blocked remainder stays staged and goes back through resolve-research once vet-source clears the source it waits on.research-topiccited, on research/<topic>PR mergesresearch/<topic>.mdon record, unresolvedresolve-researchown PRPromoteopinions and templates updated, topic deletedDiscardnothing woven, topic deletedPartial promotionthe rest woven, the blocked remainder stays stagedonce vet-source clears its source

House opinions

House opinions are preferences from experience, which no vetted source backs. Each belongs to a house profile, owned by a person or an organisation. The site shows none by default, so every page is sourced community practice. To see a profile's house opinions, choose it in the header. Each one starts with House: and appears next to the sourced recommendation it changes. For how profiles work, including private ones for your own organisation, see House profiles.