diff --git a/skills/km/SKILL.md b/skills/km/SKILL.md index 3db6bc3..e29dca9 100644 --- a/skills/km/SKILL.md +++ b/skills/km/SKILL.md @@ -45,9 +45,9 @@ When the user runs `/km init` (or confirms after "CONVENTIONS.md missing" prompt ## Team brain init (`/km init --team`) A **team brain** is a shared, served knowledge base: one maintainer merges, the team reads the repo, -everyone else contributes by fork PR or promotes from a personal brain. On top of a personal brain +everyone else contributes by pull request or promotes from a personal brain. On top of a personal brain it adds CI (validation, a generated `_index.md` Documents list, a served bundle, weekly staleness -demotion), domain folders instead of `inbox/`, and the single-writer rules. +demotion), domain folders instead of `inbox/`, and the one-merger rules. 1. Ask for: the brain's name (e.g. `QA-Brain`), a one-line description of the team (e.g. `the QA team`), the maintainer's initials, and the top-level folders with a one-line purpose each @@ -67,7 +67,7 @@ demotion), domain folders instead of `inbox/`, and the single-writer rules. 5. Tell the user what km does not do: create the repo (private), push `main`, give the team **read** access and the maintainer write, and ask members to add the brain to their personal brain with `/km brain add `. Branch protection on a private repo needs a paid GitHub plan; without it - the single-writer rule is held by the permission model alone. Contributions arrive as fork PRs, + the one-merger rule is held by the permission model alone. Members with read access contribute by fork PR, and GitHub does not run Actions on fork PRs of a private repo until "Run workflows from fork pull requests" is enabled (repository or organization settings, Actions): without it those PRs get no CI. Dependabot then proposes a PR whenever a newer km is released. diff --git a/src/km/init.py b/src/km/init.py index 02c743d..5d2366b 100644 --- a/src/km/init.py +++ b/src/km/init.py @@ -125,7 +125,7 @@ def render(a: argparse.Namespace) -> dict[str, str]: def main() -> int: ap = argparse.ArgumentParser(prog="km init", description="Create a brain from km's templates.") ap.add_argument("repo") - ap.add_argument("--team", action="store_true", help="a shared team brain (CI, served bundle, one writer)") + ap.add_argument("--team", action="store_true", help="a shared team brain (CI, served bundle, one merger)") ap.add_argument("--initials", required=True, help="the owner's or maintainer's initials") ap.add_argument("--folder", action="append", metavar="DIR=PURPOSE") ap.add_argument("--name", help="team brain: its name, e.g. QA-Brain") diff --git a/src/km/templates/team/CLAUDE.team.template.md b/src/km/templates/team/CLAUDE.team.template.md index f65efc9..a096c76 100644 --- a/src/km/templates/team/CLAUDE.team.template.md +++ b/src/km/templates/team/CLAUDE.team.template.md @@ -9,9 +9,9 @@ promoted here. ## Access & contribution model -- **One writer.** Only the maintainer commits to `main`; everyone else reads. Contribute via a - **fork PR** (the maintainer reviews and merges) or by **promoting** from your personal brain with - `km promote`. +- **One merger.** Only the maintainer merges to `main`; everyone else reads. Contribute via a + **pull request** (the maintainer reviews and merges) or by **promoting** from your personal brain + with `km promote`. - **Uphill-only:** a served doc never links into a personal brain; personal brains link up to here. ## How to Contribute diff --git a/src/km/templates/team/CONVENTIONS.team.template.md b/src/km/templates/team/CONVENTIONS.team.template.md index 7cff7bb..f3ae8a3 100644 --- a/src/km/templates/team/CONVENTIONS.team.template.md +++ b/src/km/templates/team/CONVENTIONS.team.template.md @@ -7,11 +7,11 @@ shared, served knowledge base. For frontmatter, [km's base schema](https://githu ## Access & reading model -- **One writer.** Only the maintainer commits to `main`; everyone else has **read** access to the - repository and reads the markdown directly. Contributions come as a **fork PR** (the maintainer - reviews and merges) or are **promoted** from a personal brain via `km promote`. Because - only the maintainer commits, git history shows the maintainer, not per-author activity; the - `author` field records who authored the knowledge (provenance, not a performance metric). +- **One merger.** Only the maintainer merges to `main`; everyone else has **read** access to the + repository and reads the markdown directly. Contributions come as a **pull request** (the + maintainer reviews and merges) or are **promoted** from a personal brain via `km promote`. Git + history and pull requests show each contributor; they serve provenance, never per-person + analysis. The `author` field records who authored the knowledge. - **Curated corpus, not a workshop.** The holds finished, reviewed knowledge; drafts and half-thoughts stay in personal brains. `status` marks maturity: read `accepted` as current and authoritative, `review` as submitted, `draft` as work in progress. @@ -139,4 +139,4 @@ is stale or a folder with something to list has no `_index.md` (`km gen-index -- - Relative markdown links in bodies; `related:` / `supersedes:` / `superseded_by:` use **repo-root-relative** paths. Never duplicate content, link. - Conventional Commits `type(scope): description`; the PR title carries the ticket key. Work on a - branch named by the ticket key; `main` is protected by the single-writer permission model. + branch named by the ticket key; `main` is protected by the one-merger permission model. diff --git a/src/km/templates/team/README.team.template.md b/src/km/templates/team/README.team.template.md index 4ba3ab5..41dc834 100644 --- a/src/km/templates/team/README.team.template.md +++ b/src/km/templates/team/README.team.template.md @@ -4,6 +4,6 @@ (repo read access); an optional CI-built bundle feeds AI/RAG tools. - **Rules:** [CONVENTIONS.md](CONVENTIONS.md) (authoritative; enforced by `km validate`). -- **How to contribute:** [CLAUDE.md](CLAUDE.md), one writer, others via fork PR or promote from a - personal brain. +- **How to contribute:** [CLAUDE.md](CLAUDE.md): a pull request, or promote from a personal brain; + the maintainer merges. - **Layout:** the top-level folders are listed in [_index.md](_index.md).