diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 3fea33c..4c6ce1b 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,7 +1,7 @@ ## Tracking - Repository Issue: -- Canonical task or exception: +- Canonical task or exception: ## Summary @@ -14,7 +14,7 @@ ## Impact Checklist - [ ] I did not include credentials, tokens, sensitive configuration, or private security details. -- [ ] I linked the canonical task, or this is an eligible `.github` or `codegeist-ai/codegeist-ai` fix and I explained why no local task is needed. +- [ ] I linked the applicable canonical task, or the owning repository permits no new task and I recorded the maintainer-approved reason. - [ ] I assessed security implications and used private reporting where required. - [ ] I assessed whether documentation, tests, or repository-specific checks need updates. - [ ] I assessed whether a generated `release` branch needs an update. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 92dde2a..208b99d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,21 +4,26 @@ Thank you for improving Codegeist. This guide is the account-wide default; instructions in the target repository take precedence when they are more specific. +Read the [GitHub account and repository model](GITHUB_ACCOUNT_MODEL.md) when you +are unsure which repository owns a change or why the two account infrastructure +repositories exist. + ## Workflow -Source-repository implementation work follows one traceable path: +Ready source-repository implementation work follows one traceable path: ```text -Project -> repository Issue -> repository docs/tasks/.../task.md -> branch -> PR -> merge +Project -> repository Issue -> canonical repository task -> branch -> PR -> merge ``` 1. Use the [public roadmap](https://github.com/users/codegeist-ai/projects/1) to understand priority and status. 2. Open or select an Issue in the repository that owns the change. Keep the Issue focused on the user-visible problem, outcome, and public discussion. -3. Link the Issue to its ready canonical `docs/tasks/.../task.md` before - implementation begins. The task records acceptance criteria, file targets, - and verification details close to the code. +3. Before the Issue is marked `status:ready`, link it to its canonical task under + `docs/tasks/`. The task may use the repository's flat or nested task form and + records acceptance criteria, file targets, and verification details close to + the code. 4. Create a small branch from the current `main`, implement the task, and run the target repository's documented checks. 5. Open a pull request that links the Issue and task, explains the result, and @@ -26,14 +31,16 @@ Project -> repository Issue -> repository docs/tasks/.../task.md -> branch -> PR 6. Merge only after review and all checks required by that repository pass. The roadmap is the public view of priorities, an Issue is the repository-level -unit of discussion, and a task file is the implementation contract. Source -implementation in `codegeist` or either shared kit requires all three links. +unit of discussion, and a task file is the implementation contract. Source work +advertised as ready in `codegeist` or either shared kit requires all three links. +For a small unplanned fix, follow the owning repository's local guide to determine +whether maintainers require a new task before the pull request. Always link an +existing task when one already defines the work. A tiny policy, profile, or documentation-only fix in `.github` or `codegeist-ai/codegeist-ai` may omit a local task. Its pull request must still link a repository Issue and state `No local task needed:` followed by a brief -reason. Existing tasks must always be linked; this exception does not apply to -source-repository implementation work. +reason. Existing tasks must always be linked. ## Forks, Branches, And Pull Requests @@ -42,9 +49,10 @@ source-repository implementation work. - Contributors with write access may use a branch in the target repository. - Keep branches focused and up to date. Do not mix unrelated fixes. - Explain behavior changes and update relevant documentation and tests. -- Link the repository Issue and canonical task in every source implementation - pull request. Use the documented no-task exception only in the two account - infrastructure repositories. +- Link the repository Issue in every source pull request. Link the canonical task + whenever the Issue is ready or an existing task defines the work. If the owning + repository's local guide permits a small unplanned fix without a new task, state + `No local task needed:` and the maintainer-approved reason in the pull request. There is no single account-wide build command. Each repository documents its normal local check in its README, contribution guide, task file, or automation diff --git a/FUTURE_REPOSITORY_CHECKLIST.md b/FUTURE_REPOSITORY_CHECKLIST.md index 1dc04c4..f82a956 100644 --- a/FUTURE_REPOSITORY_CHECKLIST.md +++ b/FUTURE_REPOSITORY_CHECKLIST.md @@ -2,7 +2,9 @@ Use this baseline when creating or opening another public repository under `codegeist-ai`. Check inherited defaults as well as files stored directly in the -new repository. +new repository. Read [`GITHUB_ACCOUNT_MODEL.md`](GITHUB_ACCOUNT_MODEL.md) first so +the new repository fits the existing ownership, planning, release, and policy +model. ## Purpose And Ownership @@ -18,6 +20,9 @@ new repository. - [ ] Confirm that effective contribution, conduct, security, support, Issue, and pull request files come from `codegeist-ai/.github` or deliberate local overrides. +- [ ] If any local `.github/ISSUE_TEMPLATE/` file is added, copy or recreate every + shared form and contact link that should remain available because GitHub stops + inheriting the entire default issue-template directory. - [ ] Document one normal local check that contributors can run before a pull request. - [ ] Document the local `docs/tasks/.../task.md` format and how tasks link to diff --git a/GITHUB_ACCOUNT_MODEL.md b/GITHUB_ACCOUNT_MODEL.md new file mode 100644 index 0000000..fdedbd0 --- /dev/null +++ b/GITHUB_ACCOUNT_MODEL.md @@ -0,0 +1,353 @@ +# Codegeist GitHub Account And Repository Model + +This document is the canonical explanation of how the public repositories under +the personal GitHub account [`codegeist-ai`](https://github.com/codegeist-ai) fit +together. It covers the two GitHub-special repositories, source ownership, +generated releases, contributor planning, shared policies, checks, security, and +the consequences of a future move to a GitHub organization. + +## Quick Answer: Why `codegeist-ai/codegeist-ai` Exists + +`codegeist-ai` is currently a personal GitHub account, not a GitHub organization. +GitHub renders a personal profile README only when the account owns a public +repository whose name exactly matches the account name: + +```text +codegeist-ai / codegeist-ai +account profile repository +``` + +The root `README.md` from +[`codegeist-ai/codegeist-ai`](https://github.com/codegeist-ai/codegeist-ai) +therefore appears on the public account page at +[`github.com/codegeist-ai`](https://github.com/codegeist-ai). + +This profile repository is not the Codegeist product, a package, a mirror, or a +second copy of the source. It contains only profile/discovery documentation, its +license, and a small repository check. + +The separate [`codegeist-ai/.github`](https://github.com/codegeist-ai/.github) +repository has another GitHub-special role: it supplies default community health +files to public repositories owned by the account. It does not render the personal +profile. A `.github/profile/README.md` is the organization-profile convention and +does not replace the username-matching repository for this personal account. + +## Public Repository Inventory + +| Repository | Responsibility | Editable source | Distribution | Normal check | +| --- | --- | --- | --- | --- | +| [`codegeist-ai/.github`](https://github.com/codegeist-ai/.github) | Account-wide community policies, issue forms, pull-request template, and repository baseline | `main` | GitHub inherits files directly | `bash scripts/check.sh` | +| [`codegeist-ai/codegeist-ai`](https://github.com/codegeist-ai/codegeist-ai) | Personal account profile and public repository map | `main` | Root `README.md` renders on the account profile | `bash scripts/check.sh` | +| [`codegeist-ai/codegeist`](https://github.com/codegeist-ai/codegeist) | Core Java CLI/TUI product, providers, MCP, local tools, installers, and user releases | `main` | Tagged GitHub Releases and downloadable artifacts | `task cli:check` | +| [`codegeist-ai/codegeist-agent-kit`](https://github.com/codegeist-ai/codegeist-agent-kit) | Reusable OpenCode rules, commands, skills, plugins, and configuration | `main` | Generated `release` branch consumed at `.opencode/` | `task test` | +| [`codegeist-ai/codegeist-devcontainer-kit`](https://github.com/codegeist-ai/codegeist-devcontainer-kit) | Reusable development image, initialization, Compose runtime, and workspace tooling | `main` | Generated `release` branch consumed at `.devcontainer/` | `task check` | + +All five repositories contain Codegeist-owned material and have their own root +`LICENSE`. A license is never inherited from `.github`. + +## Ownership Decision Guide + +Choose the repository by the behavior being changed: + +| Change | Owning repository | +| --- | --- | +| Codegeist CLI/TUI behavior, provider integration, MCP, local tools, installers, or product release automation | `codegeist` | +| Generic OpenCode agent rules, commands, skills, plugins, MCP configuration, or shared AI workflow | `codegeist-agent-kit` | +| Devcontainer image, installed toolchain, browser launcher, Compose runtime, initialization, worktrees, or development-environment behavior | `codegeist-devcontainer-kit` | +| Account-wide contribution, conduct, security, support, issue, or pull-request policy | `.github` | +| Text displayed on the personal GitHub account profile or the short ecosystem map | `codegeist-ai/codegeist-ai` | + +Project-specific behavior does not belong in either shared kit. Consuming +repositories keep project-only OpenCode behavior in `.oc_local/` and documented +devcontainer overrides under `.codegeist/`. + +## GitHub-Special Repository Behavior + +### `.github`: Default Community Files + +The public `.github` repository owns these account defaults: + +- `CONTRIBUTING.md` +- `CODE_OF_CONDUCT.md` +- `SECURITY.md` +- `SUPPORT.md` +- `.github/ISSUE_TEMPLATE/*` +- `.github/PULL_REQUEST_TEMPLATE.md` + +For standalone community files, GitHub applies a default only when the target +repository does not provide a local file of the same type. A local file takes +precedence. This is why the three source repositories keep repository-specific +`CONTRIBUTING.md` files while inheriting account-wide conduct, security, support, +issue, and pull-request files. + +Issue templates are a directory-level exception. If a repository adds any local +file under `.github/ISSUE_TEMPLATE/`, including `config.yml`, GitHub stops +inheriting the default issue-template directory. A repository that needs one custom +form must also copy or recreate every shared form and contact link it still wants. + +The `.github` repository cannot provide another repository's license. Every +Codegeist-owned repository must carry and maintain its own root `LICENSE`. + +### `codegeist-ai/codegeist-ai`: Personal Profile + +The username-matching repository owns the profile rendered at +[`github.com/codegeist-ai`](https://github.com/codegeist-ai). Its README should +stay concise and public-facing: + +- explain what Codegeist is; +- map the public repositories; +- direct contributors to the correct owner; +- link the Roadmap and shared contribution guide; +- show each repository's normal check. + +Detailed policies and maintenance contracts belong in `.github`, not in the +profile README. The profile repository deliberately relies on the inherited +community files from `.github`. + +## Public Planning And Task Model + +The public workflow is: + +```text +Codegeist Roadmap -> owning repository Issue -> canonical local task -> branch -> pull request -> merge +``` + +Responsibilities are intentionally separate: + +- The public [Codegeist Roadmap](https://github.com/users/codegeist-ai/projects/1) + gives the cross-repository priority and status view. +- A repository Issue owns public discussion, assignment, labels, and the user- or + maintainer-visible outcome. +- A canonical task under the owning repository's `docs/tasks/` owns detailed scope, + acceptance criteria, file targets, non-goals, and verification. +- A pull request links the Issue and task, reports checks, and delivers the change. + +Task IDs are repository-local. Always link the repository and complete path; do not +assume `T001` in one repository refers to `T001` in another. + +The Roadmap uses these workflow states: + +- `Backlog` +- `Ready` +- `In Progress` +- `In Review` +- `Done` + +It also records repository, area, effort, and contribution level. `good first +issue` is reserved for genuinely beginner-safe work. Security policy, permissions, +secret handling, release mutation, and broad architecture remain maintainer-led. + +Every source Issue advertised as `status:ready` has a canonical local task. Small +unplanned fixes may follow the owning repository's more specific guide, which +decides whether a new task is needed before a pull request. Existing tasks are +always linked. Small policy/profile documentation fixes in `.github` or +`codegeist-ai/codegeist-ai` may use the documented no-local-task exception. + +## Source, Generated Releases, And Consumers + +The two kit repositories separate source from distribution: + +```text +source main + -> source pull request and normal check + -> maintainer release build + -> generated release branch + -> consumer submodule/gitlink update + -> consumer pull request and check +``` + +Important constraints: + +- Implement changes on the kit's source `main` branch. +- Never implement directly on a generated `release` branch. +- Never customize a kit by editing a consuming `.opencode/` or `.devcontainer/` + submodule checkout. +- Publish the generated release only through that kit's documented release workflow. +- Update consumer gitlinks only after the matching release commit exists remotely. +- Keep source, release, and consumer updates traceable as separate steps. + +The core `codegeist` repository uses tagged GitHub Releases rather than a generated +source-subset branch. Its release workflow builds the JAR, native archives, +installers, checksums, and the standalone license asset. + +## Checks And Protected Branches + +Each repository has a deterministic normal check and a matching required GitHub +Actions context: + +| Repository | Local command | Required `main` check | +| --- | --- | --- | +| `.github` | `bash scripts/check.sh` | `check` | +| `codegeist-ai/codegeist-ai` | `bash scripts/check.sh` | `check` | +| `codegeist` | `task cli:check` | `JVM check` | +| `codegeist-agent-kit` | `task test` | `test` | +| `codegeist-devcontainer-kit` | `task check` | `Check` | + +The normal checks stay smaller than release or environment-heavy validation. For +example, core normal CI does not call providers, download models, use Docker, build +native images, or run QEMU. Devcontainer changes that affect images, browser +runtime, Docker/Compose, QEMU, or lifecycle behavior additionally require the full +`task tests-run` suite before release publication. + +All public `main` branches currently enforce: + +- changes through pull requests; +- the repository's proven required check; +- strict up-to-date branches before merge; +- linear history; +- resolved review conversations; +- no force pushes; +- no branch deletion; +- the same rules for the maintainer account. + +The required approval count is zero while there is only one maintainer. This keeps +the pull-request and CI gate without creating an impossible self-approval rule. + +## Licensing And Third-Party Material + +Codegeist-owned source and documentation use the OSI-approved Zero-Clause BSD +License, SPDX identifier `0BSD`. Intentional contributions are accepted under the +same terms without a CLA or DCO requirement. + +The root license does not relicense third-party dependencies, vendored content, +submodules, notices, or upstream-derived material. Preserve every applicable +third-party license and attribution. + +Both generated kit `release` branches include the canonical `LICENSE`. Core JAR and +native release packaging carries the same license through the existing release +workflow. + +## Security, Conduct, And Support + +- Suspected vulnerabilities must not be posted in public Issues, pull requests, + tasks, the Roadmap, or Discord. +- Every public repository has GitHub private vulnerability reporting enabled. +- The confirmed private fallback for vulnerability and conduct reports is + `dev@codegeist.ai`. +- Never include credentials, tokens, private keys, personal data, or sensitive + configuration in reports or examples. +- Codegeist does not claim that the core tool runtime or development environment is + a security sandbox. +- Reproducible bugs and scoped feature requests belong in the owning repository's + Issues. +- Informal help belongs in the + [Codegeist Discord](https://discord.gg/nh7XUkmsW7), but actionable work moves to + GitHub Issues. + +See [`SECURITY.md`](SECURITY.md), [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md), and +[`SUPPORT.md`](SUPPORT.md) for the complete policies. + +## Maintaining The Two Account Repositories + +To change shared policies or templates: + +1. Work in `codegeist-ai/.github` on a branch from `main`. +2. Run `bash scripts/check.sh`. +3. Open a pull request and wait for the required `check` context. +4. Merge through the protected `main` branch. +5. Verify inheritance and community profiles in affected repositories. + +To change the visible personal profile: + +1. Work in `codegeist-ai/codegeist-ai` on a branch from `main`. +2. Edit the root `README.md`. +3. Run `bash scripts/check.sh`. +4. Open a pull request and wait for the required `check` context. +5. Merge and verify the rendered account page at + [`github.com/codegeist-ai`](https://github.com/codegeist-ai). + +For a cross-repository documentation change, publish and verify the target in +`.github` before merging any profile or source-repository document that links to +it. This ordering prevents public contributor guidance from temporarily pointing +at a missing policy or model document. + +Do not copy profile content into `.github/profile/README.md` while `codegeist-ai` +remains a personal account. That path would describe an organization profile, not +the current account type. + +## Adding Another Public Repository + +Use [`FUTURE_REPOSITORY_CHECKLIST.md`](FUTURE_REPOSITORY_CHECKLIST.md) before +advertising work in a new public repository. At minimum, define ownership, add the +root license, verify inherited policies, document one normal check, prove CI, add +metadata, enable private reporting, publish task/Issue links, and protect `main`. + +After adding a public repository, update both this inventory and the profile README +in `codegeist-ai/codegeist-ai`. + +## Future Migration To A GitHub Organization + +There are two distinct migration strategies. Prefer creating a new organization and +transferring repositories when retaining the personal account and its user data is +important. GitHub cannot create an organization named `codegeist-ai` while the +personal account owns that username. To preserve the public name, first rename the +personal account, then create the `codegeist-ai` organization, and finally transfer +the repositories. Repository transfer requires permission to create repositories in +the destination organization and may be limited by organization or enterprise +policy. Plan and verify GitHub's redirects before changing stable links. + +GitHub also supports converting the existing personal account into an organization, +but conversion is permanent. Before conversion, create another personal account +that can sign in and become the organization owner, and make the account being +converted leave every organization it has joined. The converted account can no +longer be used to sign in as a person. Personal SSH keys, OAuth tokens, GitHub Apps, +gists, stars, follows, and other user data do not become organization data; review +GitHub Actions and every integration after conversion. + +For either strategy, review this model explicitly rather than assuming the special +repositories behave identically: + +- An organization profile uses `.github/profile/README.md`. +- The username-matching `codegeist-ai/codegeist-ai` repository would no longer be + required to render the organization profile. Decide whether to archive, redirect, + or repurpose it. +- The public `.github` repository can continue to provide organization-wide + community defaults. +- Roadmap URLs may move from `/users/codegeist-ai/projects/...` to an organization + project URL. +- Review repository ownership, team permissions, branch rules, security contacts, + and required approvals for the new maintainer model. +- Update all stable documentation links and verify inheritance after the migration. + +GitHub selects the profile mechanism by account type; the personal and organization +profile READMEs do not render concurrently for one account. Do not create +`.github/profile/README.md` before migration because GitHub will not use it for the +current personal profile and maintainers could edit the wrong source. + +Read GitHub's current +[account conversion guide](https://docs.github.com/en/account-and-profile/how-tos/account-management/converting-a-user-into-an-organization) +and +[repository transfer guide](https://docs.github.com/en/repositories/creating-and-managing-repositories/transferring-a-repository) +before choosing a migration strategy. + +## Audit Commands + +Maintainers can inspect the public model with authenticated GitHub CLI commands: + +```bash +gh repo list codegeist-ai --visibility public --limit 100 +gh project item-list 1 --owner codegeist-ai +gh api repos/codegeist-ai/codegeist/community/profile +gh api repos/codegeist-ai/codegeist/license +gh api repos/codegeist-ai/codegeist/branches/main/protection +gh api repos/codegeist-ai/codegeist/private-vulnerability-reporting +``` + +Repeat repository-specific API checks for `.github`, `codegeist-ai`, +`codegeist-agent-kit`, and `codegeist-devcontainer-kit`. The expected current state +is five public repositories, GitHub-detected `0BSD`, complete community profiles, +enabled private reporting, and protected `main` branches with the checks listed +above. + +## Related Documentation + +- [`README.md`](README.md) - entrypoint for the default-community repository. +- [`CONTRIBUTING.md`](CONTRIBUTING.md) - account-wide contribution workflow. +- [`FUTURE_REPOSITORY_CHECKLIST.md`](FUTURE_REPOSITORY_CHECKLIST.md) - baseline for + new public repositories. +- [`SECURITY.md`](SECURITY.md) - private vulnerability reporting. +- [`SUPPORT.md`](SUPPORT.md) - public support routing. +- [`codegeist-ai/codegeist-ai`](https://github.com/codegeist-ai/codegeist-ai) - + source of the rendered personal profile. +- [`Codegeist Roadmap`](https://github.com/users/codegeist-ai/projects/1) - public + cross-repository planning. diff --git a/README.md b/README.md index 2ce950b..cf09d0d 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,11 @@ This is the public GitHub `.github` repository for the personal account community-health files used by public Codegeist repositories when a repository does not provide its own version. +Start with [`GITHUB_ACCOUNT_MODEL.md`](GITHUB_ACCOUNT_MODEL.md) for the complete +explanation of why both `.github` and `codegeist-ai/codegeist-ai` exist, what each +public repository owns, and how planning, releases, policies, checks, and branch +protection work together. + Repository-specific files take precedence over these defaults. Maintainers should keep local instructions when a project needs different build, release, support, or security details. @@ -26,6 +31,8 @@ account. provide shared issue and pull request templates. - [`FUTURE_REPOSITORY_CHECKLIST.md`](FUTURE_REPOSITORY_CHECKLIST.md) is the baseline for new public repositories. +- [`GITHUB_ACCOUNT_MODEL.md`](GITHUB_ACCOUNT_MODEL.md) is the canonical account, + repository, planning, release, and maintenance model. ## Normal Check diff --git a/scripts/check.sh b/scripts/check.sh index 2ed2e76..53cb3dc 100755 --- a/scripts/check.sh +++ b/scripts/check.sh @@ -13,6 +13,7 @@ cd "$repo_root" required_files=( LICENSE README.md + GITHUB_ACCOUNT_MODEL.md CONTRIBUTING.md CODE_OF_CONDUCT.md SECURITY.md @@ -75,4 +76,9 @@ fi exit 1 } +grep -Fq 'GITHUB_ACCOUNT_MODEL.md' README.md || { + printf 'README.md must link the canonical GitHub account model.\n' >&2 + exit 1 +} + printf 'Community checks passed.\n'