Skip to content

docs: require origin/main worktrees and hub-repo dogfood #483

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jimpablo wants to merge 2 commits into
base: main
Choose a base branch
from
+22 −3
Open

docs: require origin/main worktrees and hub-repo dogfood #483

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e490c9d
docs: require origin/main worktrees and hub-repo dogfood
jimpablo Sep 10, 2026
c600717
docs: keep CONTRIBUTING #479 changes to the requested minimum
jimpablo Sep 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 22 additions & 3 deletions .github/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,11 +22,30 @@ npm run test:e2e # E2E tests (optional, requires a live test repo)

### Running your local build

Work in the **CLI clone**, not as `teamai init .`.

```bash
npm link
teamai --version
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
```

Documented 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 pull` still works.

`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.

| 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 |

`git status` after init does not imply committing TeamAI local files into `teamai-cli`. Do not stage `.teamai/` or tool dirs.

## Project Layout

```
Expand All @@ -43,7 +62,7 @@ See [docs/providers.md](../docs/providers.md) for how to add a new git provider.

## Making a Change

1. Fork the repo and create a feature branch from `master`.
1. Fork the repo and create a feature branch from the latest `origin/main`. Prefer a git worktree for code changes.
2. Write tests for your change (we target 80%+ coverage).
3. Run `npx vitest run` and `npx tsc --noEmit` — both must pass.
4. Use conventional commits where possible: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`.
Expand Down
Loading