New ecosystems
A new ecosystem goes through nine stages, from an empty repository to an established set of opinions. This page describes each stage, and what to expect while research outnumbers opinions. A new ecosystem's PLAN.md can link here instead of repeating the stages. Rust, started on 2026-10-14, is the worked example.
No third ecosystem starts until dotnet and rust have settled the multi-repository approach, a hold set on 2026-10-18. Problems with the approach are easier to fix across two repositories than three or more.
Stages
Each stage ends with a check you can run or read. For the full steps, see Rust's PLAN.md.
- Scaffold the repository. Copy the layout,
AGENTS.md,REVIEW.md, and CI from an existing ecosystem. Port the checks to the ecosystem's own language, such as Go for a Kubernetes ecosystem, so the repository's own code is in the language its opinions cover. AdaptREVIEW.mdto match, because it names the checks CI runs and the toolchain an example must build with. From then on, a pull request that changes one ecosystem'sREVIEW.mdlinks the matching pull request in each other ecosystem, or says why that one doesn't need the change. Done whenjust verifypasses on emptyopinions/,research/, andtemplates/directories. - Vet the roster. Run
vet-sourcefor each candidate inAWESOME-HUMANS.md. Done when each topic in the plan's first-opinions table has a Citable source expected to support it. - Name the references. Under Named references in
AWESOME-HUMANS.md, list the repositories that count as references, and the link form for each. Done before the firstresearch-topicrun, because most topics cite a reference. - Add the skills. Copy them from an existing ecosystem, and adapt them. Done when each skill's
SKILL.mdnames the repository and its paths, andskills-refvalidates it. - Join the site. Add the ecosystem to
ecosystems.tomlin thewebsiterepository withstatus = "soon", and follow the other steps in its README. The home page then shows it as coming, and only previews of its own pull requests build it. Done when a preview stages its pages. - Research the first topics. Run
research-topicfor each topic in the plan's table, one pull request each. Done when every topic in the table has merged. - Resolve them into opinions. Run
resolve-researchfor each merged topic, and setstatus = "live"when the first opinion merges. Done when the ecosystem is live. Rust went live on 2026-10-18: rust#18 mergedopinions/rust.md, and website#91 published it the same day. - Hold the checks to the opinions. Read every check written in the ecosystem's language against its opinions and templates, and fix what doesn't follow them, so the repository follows the practices it recommends. Done when every check has been read against them, and the fixes have merged.
- Delete the plan. Once every topic in the table is promoted or discarded, delete
PLAN.mdin the pull request that resolves the last one. The ecosystem is then established.
While research outnumbers opinions
This happens in stages 6 to 9. On 2026-10-25, Rust had one opinion, two merged topics waiting on resolve-research, and seven topics in open pull requests. That's normal, and so are these:
- Readers and agents see little of the research. The site marks a merged topic with an "Unresolved research" lead. The ecosystem's
llms.txtlists opinions, templates, and skills, but never research. A topic in an open pull request isn't on the site at all. - Research finds gaps in the rules. Topics written in parallel apply an unsettled rule in different ways: Rust's open topics linked RFCs and RustSec advisories in three URL forms before rust#60 settled them. Fix the rule in its own pull request, then check each open topic against it. Don't fix it inside a research pull request, because the other topics won't see it.
- Topics need sources the plan didn't expect. The plan expected
research/rust.mdto draw its idioms fromrust-docs,rust-blog, andniko-matsakis. It drew onburntsushi,corrode, andmatkladinstead, which were already Citable. When a source isn't on the roster, runvet-sourcefor it, or promote the covered part and leave the rest staged. - Resolve in the plan's order. The table puts the foundations first, such as the language and project structure, so a later opinion can link to an earlier one instead of restating it.
Skills with few opinions
Most skills work on opinions, so before stage 7 they have little to do. Read their results with that in mind:
audit-freshnessreports nothing to check while the repository has no opinions, and fails. It flags a research topic 90 days after itslast-revieweddate, so a merged topic left unresolved becomes a finding.review-projectcompares a project only with the areas the opinions cover. A short report from few opinions means little coverage, not a compliant project.review-opinionschecks only opinions and templates, so before stage 7 it has little more than the template comments to read. Run a full pass when the first opinion merges, so the opinions start from citations known to hold. After that,harvest-sourceschecks the citations each harvest changes.- The agent reviewer follows
REVIEW.md, whose Important findings cover opinions, templates, skills, and checks. The one Important finding specific to research is a rule changed alongside a topic, so the maintainer's review covers the rest of a research pull request. harvest-sourcesedits an existing opinion when a post fits one. For a post on any other topic, it first checksresearch/and the open research pull requests, and adds the post to a topic that covers it. If none does, it adds a stub opinion.- The version refresh skill, such as
refresh-rust-versions, updates opinions and templates only. Research topics keep the versions they were written against untilresolve-researchupdates them.