docs: fix CONTRIBUTING branch baseline and require dogfooding the public team repo
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 4.8k
- Forks
- 342
- Avg merge
- 13h 48m
- Merged PRs (30d)
- 211
Description
Summary
.github/CONTRIBUTING.md is wrong on the default branch, and it never asks CLI contributors to run TeamAI against a TeamAI team repo (dogfooding / bootstrap).
Problems
- Wrong branch. "Making a Change" tells people to create a feature branch from
master. The default branch of this repo ismain(origin/HEAD→refs/heads/main). - No dogfood setup. Contributors only
npm install/npm link. They neverteamai inita team repo, so they do not exercise pull, hooks, recall, or the contributor path while developing the CLI.
Proposed docs-only change
Update .github/CONTRIBUTING.md only (README already links there). No new CLI commands.
Branch baseline
- Create feature branches from the latest
origin/main. - Prefer a git worktree for code changes, matching existing maintainer practice.
Required dogfood (all contributors)
Create a regular (not template) public team repo under teamai-hub, e.g. https://github.com/teamai-hub/teamai-cli-dev, with main branch protection (PR + review). Put only public-safe skills / rules / docs there.
In the CLI clone (not as teamai init .):
npm run build && npm link
teamai init https://github.com/teamai-hub/teamai-cli-dev --scope project --role dev
teamai pull
git status # nothing under .teamai/ or tool dirs should be staged for this repo
Document these pitfalls:
- Init the canonical hub URL, not a personal fork.
teamai init <url>treats that URL as the team repo; a fork diverges immediately, and GitHub push/PR today targets the configured remote (no fork-to-upstream flow). - Do not run
teamai init .. That is single-repo mode: it turns the CLI source tree into the team repo and writes scaffolding at the repo root (easy to commit by mistake). Push failed (you can push manually later)on member registration is expected without write access. Local config is still saved;teamai pullstill works.
Write access and stats (do not grant write to every contributor)
digest / dashboard read stats/, sessions/, and members/ from the team repo. Those files are written via git, so no write ⇒ not in team stats.
Giving every internet contributor write on the hub repo is not acceptable.
Document the split:
| Who | Hub repo access | Required setup | In team digest |
|---|---|---|---|
| Contributors | read | init + pull |
no |
| Collaborators (after a few PRs) | write, main protected |
full, including reports | yes |
Do not document an internal / TGit contributor path in this public guide.
Out of scope
- CLI behavior changes (including fork-aware
teamai push). - HTTP report/sync/ack so read-only users appear in digest.
- Sweeping leftover
masterwording in other files (providers.md, comments, skills).
Acceptance
- CONTRIBUTING never says to branch from
master. - A contributor can complete build → link → init hub repo → pull, and understands a failed member push as normal.
git statusafter init does not imply committing TeamAI local files intoteamai-cli.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Read .github/CONTRIBUTING.md and compare its branch instructions with the issue’s required build, link, init, and pull flow. Update that file only so it uses origin/main, explains public team-repo dogfooding, access limitations, and expected push failures. Verify the documented acceptance points, including a clean git status after initialization.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, github
- Domain
- cli, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 86/100