Scenario: Admin — set up a new team repo from scratch
Goal: the user becomes the first admin of a brand-new TeamAI team. At the end they have a working team repo URL to share with members.
Run the commands yourself. Only stop to ask when a step says "ASK".
Step 1 — Install and verify
npm install -g teamai-cli
teamai --versionIf teamai --version fails, Node.js ≥ 20 is missing. Tell the user to install
Node 20+ (from https://nodejs.org), then retry. Do not continue until the version
prints.
Step 2 — Pick a Git platform (only when the user gave NO repo URL)
If the user already gave a full repo URL, skip to Step 4. Otherwise, TeamAI needs a place to store the team's skills/rules. The user does not need to know Git. Work through these sub-steps in order:
2a — Ask which platform they know
Tencent-internal first: before asking, probe whether TGit is reachable
on this machine — see {SKILL_DIR}/references/provider-tgit.md ("Probe
reachability") for the one-line x-env: tgit check. If it says tgit: OK, list Tencent TGit first and
prefer it. Then ask: "Have you heard of / do you have an account on any of these —
Tencent TGit, GitHub, GitLab, or CNB (cnb.cool)?"
- Tencent TGit — https://git.woa.com (Tencent-internal only; shown
first when the probe above says
tgit: OK) - GitHub — https://github.com
- GitLab — https://gitlab.com (or a self-hosted company GitLab)
- CNB — https://cnb.cool
If they name one, use that platform and go to sub-step 2c.
2b — If they've heard of NONE, auto-probe reachability
Test which sites this network can actually reach (probe each, ~3s timeout each).
The TGit probe checks the x-env: tgit header, not just reachability (see
{SKILL_DIR}/references/provider-tgit.md); the others just check reachability:
curl -sS -m 3 -D - -o /dev/null https://git.woa.com 2>/dev/null | grep -qi '^x-env:[[:space:]]*tgit' && echo "tgit: OK" || echo "tgit: unreachable"
curl -sSf -m 3 -o /dev/null https://github.com && echo "github: OK" || echo "github: unreachable"
curl -sSf -m 3 -o /dev/null https://gitlab.com && echo "gitlab: OK" || echo "gitlab: unreachable"
curl -sSf -m 3 -o /dev/null https://cnb.cool && echo "cnb: OK" || echo "cnb: unreachable"- TGit reachable (
tgit: OK) → prefer Tencent TGit; it is the Tencent-internal default. - Exactly one reachable → use that one.
- Several reachable → list them (TGit first when present) and let the user pick.
- None reachable → stop. Tell the user to ask their own admin for a ready-made
repo URL, then switch to
{SKILL_DIR}/references/join-member.md.
Choose by account + reachability only — never by region.
2c — Give the sign-up / create link and let them create the project
Once the platform is decided, hand the user the direct link to sign in and create the repository, then continue to the next step:
| Platform | Sign in / sign up | Create a new repo (do this) |
|---|---|---|
| Tencent TGit | https://git.woa.com | https://git.woa.com/projects/new |
| GitHub | https://github.com/login | https://github.com/new |
| GitLab | https://gitlab.com/users/sign_in | https://gitlab.com/projects/new |
| CNB | https://cnb.cool | https://cnb.cool/new/repos (org first: https://cnb.cool/new/groups) |
Tencent TGit: don't send the user to the browser to create the repo — prefer letting
teamai initcreate it via the API in Step 5. See{SKILL_DIR}/references/provider-tgit.md("When youteamai initon TGit").
Tell the user to sign in, create an empty repo (suggested name
<team-name>-teamai), and give you the resulting repo URL. Explain in one
sentence: "The repo on the website is where the team's skills and rules live; your
computer only holds a synced copy — you never put business code in it."
You may instead let
teamai initcreate the repo from the CLI in Step 5 (it offers to create a missing repo on GitHub/GitLab). Creating it in the browser first is the simplest path for a user who does not know Git, and is required on CNB (see the CNB caveat in Step 5).
Step 3 — Log in from the CLI
Signing in on the website (Step 2c) is not enough — teamai init also needs the
platform's CLI credentials. Have the user complete the matching CLI login:
Tencent TGit
See {SKILL_DIR}/references/provider-tgit.md ("Log in") — you install gf and
run gf auth login yourself; the user only approves in the browser / iOA. No GITLAB_URL needed.
Then return here for Step 4.
CNB — install the CLI, authorize, then read the repo (in this order)
Once the user has created their repo on cnb.cool and given you the URL, do these three steps in order:
- Install the CNB CLI (needed to talk to cnb.cool):
(npm install -g @cnbcool/cnb-cliteamai initalso installs it automatically if it is missing, but running it here first makes the next step predictable.) - Ask the user to authorize. Start the login and have them approve it in the
browser (OAuth2 device flow):
Wait for them to confirm they finished authorizing before continuing.cnb login - Then read their repo — proceed to Step 4/5 (
teamai init <their CNB URL>), which can now clone and read the repo with the authorized CLI.
(Headless/CI alternative: set CNB_TOKEN instead of cnb login.)
GitHub — YOU run the login; user only clicks approve
Don't hand the user a gh command to run — you run the login, they only approve
it in the browser. Log them in before teamai init:
gh auth login --web --git-protocol httpsThe flow prints a one-time code and a https://github.com/login/device URL.
Relay both to the user and ask them to open that URL and approve — that approval
is the only thing they do; the command finishes on its own once they do. Confirm
with gh auth status before continuing.
(Headless/CI only: skip the interactive login and pre-set GITHUB_TOKEN — a token
with repo scope — instead.)
GitLab (gitlab.com)
Set a Personal Access Token with api scope. Prefer a short-lived token and
pull it from a secret manager or a no-echo prompt rather than typing the literal
value (a pasted export lands in shell history and process listings):
read -rs GITLAB_TOKEN && export GITLAB_TOKEN # paste when prompted; not echoedSelf-hosted GitLab: also set the instance URL first —
export GITLAB_URL=https://git.example.com. Run unset GITLAB_TOKEN when
teamai init is done.
For GitHub/GitLab, teamai init installs any helper CLI it needs automatically.
Step 4 — Decide the scope (ASK)
One choice — this workspace or the whole machine?
- Default (workspace): resources land in the current workspace's
.claude/etc.cdinto the workspace first. - Whole machine: add
--scope userso every project gets the team resources. - A folder holding several repos (a workspace): set up each repo, then run the
same
initin the folder. It also receives what each repo inside selects.
(The repo name was already chosen when the user created the repo in Step 2c —
suggested form <team-name>-teamai.)
Step 5 — Initialize (you run it)
Use the full URL, never owner/repo:
Ask whether the user wants to activate any logical projects this team repo
declares. If init lists Available projects, show the names/IDs and ask
which belong to this setup; enter the corresponding comma-separated numbers.
Press Enter for none only when the user explicitly chooses no project. If the
IDs are already known, pass --project id1,id2 to skip the picker. For a
non-interactive run, ask first and pass --project: without it, init keeps
projects: [] and prints a teamai projects set <id> follow-up instead of
waiting for a choice.
# workspace scope (default) — run from inside the project directory
teamai init https://<platform>/<org>/<repo-name>
# or whole machine
teamai init https://<platform>/<org>/<repo-name> --scope userIf the repo does not exist yet, init offers to create it — accept the prompt.
- Tencent TGit:
gfand login are already done, so init creates the repo via the API when it's missing — see{SKILL_DIR}/references/provider-tgit.md("When youteamai initon TGit"). - CNB caveat: a
cnb logintoken cannot create an org or repo — that is exactly why the CNB flow has the user create the repo on the website first (Step 2c). If the org/repo is still missing here,initprints web links (https://cnb.cool/new/groups,https://cnb.cool/new/repos) — have the user create them in the browser, then re-runteamai init. By this step the CNB CLI should already be installed and authorized (Step 3). (ACNB_TOKENwithgroup-manage:rw+group-resource:rwlets the CLI create them directly.) - GitHub caveat: if a push later fails, check the repo's default branch is
main(notmaster). - If
initdetects an unknown GitLab host, it stops and asks you to setGITLAB_URL+GITLAB_TOKEN, then retry.
If the repo has roles enabled, init asks for one or more comma-separated role
numbers when running interactively. The first number is the primary role and the
remaining numbers become additional roles; pass --role <id> for a
non-interactive run when only a primary role is needed. Without a terminal (or
with CI / TEAMAI_NONINTERACTIVE set) init never waits: a provider that
would need a browser login fails at once and names the credential to prepare —
a token for GitHub / CNB / GitLab / GitCode, and for TGit a prior gf auth login run in an interactive shell (see Step 3).
Which AI tools to set up — all of them by default (global rule 9). Do not add
--agent to restrict the install unless the user explicitly said to (e.g. "only
Claude Code"). Omitting --agent gives an interactive picker — select every AI
tool already installed on the machine. Then report back which agents were set
up, in the user's language: name the tools that will now auto-start TeamAI, and
any detected tool that was skipped and why (e.g. CodeBuddy/WorkBuddy by design),
and any installed hooks that still need trust (e.g. Codex with automatic trust
disabled or unavailable). See the troubleshooting reference, "$(teamai skill path core)/references/troubleshooting.md".
Step 6 — Verify with doctor
teamai doctor
teamai hooks list # per-tool: which AI tools actually got the hooksResolve everything doctor flags before continuing.
Don't trust the "Hooks injected into all AI tool settings" message on its own —
it prints even for tools where nothing was written. teamai doctor / teamai hooks list show the real per-tool status. Only the tool you set up (e.g. claude) is
expected to show hooks installed; others are skipped by design or not yet supported,
which is normal. Full table in the troubleshooting reference
("$(teamai skill path core)/references/troubleshooting.md"), section "Which tools actually get hooks".
Step 7 — Grant members branch access (required before they can join)
TeamAI uses the Git host's access control. After the repo exists, each member needs permission to clone it and to push branches. Leave the default branch protected. They open pull requests against it.
teamai push pushes a feature branch and opens a pull request. Reports and
learnings use the branches teamai-reports and teamai-learnings, and pushed
sessions live on teamai-reports.
Do this before handing off the invite line below. Without branch access,
teamai init or teamai push fails with a permission error.
Step 8 — Hand off to members
Everything you show here goes in the user's language (global rule 1). Only the
/teamai … line, URLs, and commands stay verbatim.
First, reassure them about privacy (say this in their language): "TeamAI does not send any of your session data to third parties. The only place anything is reported is the team repo you just set up — usage counts and knowledge go there, and raw conversation content is never uploaded." (Team reporting is opt-in and carries counts + tool names only, on a separate branch of that same repo.)
- Give the user their repo web URL to share.
- Give them a ready-to-forward invite line written in their language, with the
URL filled in. The /teamai prefix stays as-is; translate the rest:
/teamai Help me join my team's TeamAI, repo URL is <URL>Tell them to send the URL + this line to each member. - Remind them (in their language): a member's
teamai initdoes not copy team resources. They arrive on the next session start, or when the member runsteamai pull. In workspace scope, init creates a tool directory only for a tool named with--agentor picked in init's tool picker; otherwise that directory appears when the member first opens that tool in the project. Resources the team adds later arrive at the next session start.
Step 9 — What's next (guide them, don't just list commands)
Wrap up in the user's own language (global rule 1).
The user may not be comfortable with the command line, so don't just hand them a
list of teamai … commands. Instead, point them back to this skill for
day-to-day work — they can keep letting the AI run things for them:
- To manage the team later, they run (in their language):
/teamai I already have TeamAI set up, help me manage it— this loads the daily-management flow ({SKILL_DIR}/references/manage-admin.md): publishing skills, inviting members, roles / packages / env. - To share a reusable skill with the team, they run (in their language):
/teamai Share this <skill-name> skill with my team— see"$(teamai skill path core)/references/contribute-member.md". - Sharing a session's learnings needs no command from them: TeamAI prompts on
its own at the end of a session worth sharing and offers the
teamai-share-learningsworkflow, whose learning step runs theshareskill (teamai skill get share) with them; once they confirm, it can also publish and score the session. A team replaces it with its ownworkflows/teamai-share-learnings.yaml. (Only once recall is on — off by default; turn it on team-wide withsharing.recall.enabled: trueinteamai.yaml, thenteamai push. Never on a read-only HTTP source, or while a member's teamai config cannot be loaded. A team that works in English also setslanguage: enin that file so the recall rule and the TodoWrite and merged-MR hints are English only; omit it, or setzh, to keep the historical bilingual text.)
Mention the underlying commands (teamai push, teamai roles, …) only as a note
for users who do want them — the primary path is re-invoking /teamai.
Step 10 — Tell them how to leave (via the skill, not raw commands)
Finish by telling the user, in their language, that they can remove TeamAI any time — and that they don't need the command line to do it. They just re-invoke the skill and you'll handle it:
/teamai Uninstall TeamAI (in their language; the /teamai prefix stays as-is)
One line, in their language: "That removes the hooks and synced resources from your machine; your team repo on the website is untouched — you can rejoin any time with /teamai and the repo URL."
(If they ask right now, load {SKILL_DIR}/references/uninstall.md and run it for them.)