teamai-cli 0.25.0-beta.2 → 0.25.0-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamai-cli",
-  "version": "0.25.0-beta.2",
+  "version": "0.25.0-beta.3",
   "description": "TeamAI — Make Every Team AI Native (skill sync + shared knowledge base, powered by Git)",
   "type": "module",
   "bin": {

package/skills/teamai/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: teamai
+description: >-
+  Guide for TeamAI — the CLI that syncs a team's AI skills, rules, docs, and env
+  across AI coding tools (set up, join, manage, contribute, uninstall). Invoke
+  ONLY when the user explicitly runs `/teamai`. Do NOT auto-trigger from ordinary
+  conversation, even if words like "team", "skill", or "sync" appear.
+---
+
+# TeamAI — Team AI Skills & Rules Sync
+
+You are guiding a user through TeamAI. **They may not know Git.** You run the
+commands; they only make choices when you ask. Follow the steps literally —
+do not skip, reorder, or invent commands.
+
+## STEP 0 — Progressive disclosure (do this first, every time)
+
+Look at what the user typed after `/teamai`.
+
+**If they gave NO scenario** (bare `/teamai`, or only greetings/no task):
+print the menu below **exactly**, then **STOP and wait**. Take no other action —
+do not run any command, do not read any reference file yet.
+
+```
+teamai — Team AI Skills & Rules Sync
+
+Usage examples (copy one to get started):
+
+  🏗️  Admin — set up a new team repo:
+      /teamai Help me set up TeamAI for my team from scratch
+
+  🤝  Member — join an existing team:
+      /teamai Help me join my team's TeamAI, repo URL is https://...
+
+  🔧  Admin — daily management (publish & update skills, rules, MCP, env):
+      /teamai I already have TeamAI set up, help me manage it
+
+  📊  Anyone — open the team dashboard:
+      /teamai Open the TeamAI dashboard
+
+  💡  Member — share a skill with the team (just ask in plain language):
+      /teamai Share this <skill-name> skill with my team
+
+  🗑️  Anyone — remove TeamAI from this machine:
+      /teamai Uninstall TeamAI
+```
+
+> **Sharing a session's learnings is automatic — not a menu choice.** TeamAI
+> prompts on its own at the end of a session that produced something worth sharing,
+> and the **`teamai-share-learnings`** skill takes over. The user does not invoke
+> `/teamai` for it. (Only appears when the admin left team sharing enabled — on by
+> default.)
+
+**If they DID describe a scenario**, match it to one row of the table below,
+then open that reference file and follow it step by step.
+
+| The user wants to…                                  | Load this reference                      |
+|-----------------------------------------------------|------------------------------------------|
+| Set up TeamAI for a team from scratch (create repo) | `references/setup-admin.md`              |
+| Join their team (with or without a repo URL)         | `references/join-member.md`              |
+| Manage a team: publish/update skills, rules, MCP, env, invite members | `references/manage-admin.md`  |
+| Share / publish a skill with the team ("share this xxx skill") — any member, not just admins | `references/contribute-member.md` |
+| Open the team dashboard (web UI)                    | run `teamai dashboard` (see cheat sheet) |
+| Remove / uninstall TeamAI from this machine         | `references/uninstall.md`                |
+
+> **Sharing session learnings is automatic, via a separate skill — do not route it
+> here.** TeamAI prompts on its own at the end of a session worth sharing, and the
+> **`teamai-share-learnings`** skill summarizes the session and runs
+> `teamai contribute`. The user does not ask for it through `/teamai`. (Only when
+> the admin left team sharing on — the default.) `contribute-member.md` here is for
+> a member **publishing a reusable skill** on request ("share this xxx skill with
+> my team").
+
+Choosing between "set up" and "join": a user **setting up a new team** becomes its
+admin and creates the repo; a user **joining an existing team** needs a repo URL
+from their admin. If someone wants to join but has no URL, that is still the
+**join** flow — `join-member.md` tells them to ask their admin for it. Do **not**
+send a would-be member to the setup/create-repo flow just because they lack a URL.
+
+If the request is ambiguous (e.g. "help me with teamai" with no direction),
+ask ONE short question to pick a row, then proceed. When something breaks at any
+step, load `references/troubleshooting.md`.
+
+## Global rules (apply to every scenario)
+
+1. **Reply in the user's language — including every example and hand-off blurb.**
+   Answer in whatever language the user used to invoke the skill (Chinese in →
+   Chinese out, English in → English out, and so on), for the whole conversation.
+   This applies to **everything you write**, not just prose: the reference files
+   below are written in English, but any ready-made sentence they hand you — the
+   invite line you give an admin to forward to members, the one-line explanations,
+   the "what's next" summary — **must be translated into the user's language before
+   you show it.** Do not paste an English example at a Chinese-speaking user.
+   *Only* commands, flags, URLs, file paths, and code identifiers stay verbatim
+   (never translate `teamai pull`, `--scope user`, `/teamai`, a repo URL, etc.).
+   Example: for a Chinese user, the member-invite line becomes
+   `/teamai 帮我加入团队的 TeamAI，仓库地址是 https://...`, not the English form.
+2. **Never teach Git.** Do not mention branches, commits, clone, or push/pull of
+   Git itself. TeamAI hides all of that. The user thinks in terms of "my team's
+   skills", not repositories.
+3. **Always use a full URL** for the team repo (e.g.
+   `https://github.com/yourorg/yourrepo`). Never use the `owner/repo` short form.
+4. **You run the commands.** Only pause to ask the user when you need a web login,
+   a value only they know, or a genuine either/or choice. Show each command before
+   you run it, in one short line.
+5. **Detect the current AI tool first.** TeamAI behaves differently per host. Note
+   which tool this conversation is running in (Claude Code, Cursor, CodeBuddy,
+   WorkBuddy, ChatGPT App, Codex, OpenCode, Kiro, Gemini CLI, …). When you reopen a
+   session, use the name of **this** tool — do not assume Claude Code or Cursor.
+   Some hosts need extra manual steps for hooks — see
+   `references/troubleshooting.md` ("Agent-specific caveats").
+6. **Prerequisite:** Node.js ≥ 20. Install once with `npm install -g teamai-cli`
+   and verify with `teamai --version`.
+7. **Finish with `teamai doctor`.** Every setup/onboarding flow ends by running
+   `teamai doctor` and resolving whatever it reports before you call it done.
+8. **After init, resources appear on the NEXT session.** `teamai init` injects a
+   session-start hook that auto-runs `teamai pull`. It is normal that the skills/
+   rules directories are empty right after init — they fill in when the user opens
+   a fresh session in this tool. To sync immediately, run `teamai pull`.
+9. **Don't limit which AI tools get set up — cover all of them by default.** Unless
+   the user explicitly says "only install to Claude Code" (or names specific
+   tools), do **not** pass `--agent` to restrict the install. Let `teamai init` set
+   up **every AI tool already installed on the machine** (omitting `--agent` gives
+   an interactive picker; select all detected tools, or the user's stated subset).
+   **After init, report which agents were set up** — tell the user, in their
+   language, exactly which tools will now auto-start TeamAI (and which detected
+   tools were skipped and why, e.g. Codex trust-gate / CodeBuddy design). Verify
+   the real per-tool result with `teamai doctor` / `teamai hooks list`.
+
+## Command cheat sheet (ground truth — do not invent flags)
+
+```bash
+teamai init <full-repo-url>       # Set up / join a team (configure provider, clone, register)
+teamai init <url> --scope user    # Install for the whole machine instead of just this project
+teamai pull                       # Sync team resources into local AI tools now
+teamai push                       # Publish your local skills/rules/docs to the team
+teamai doctor                     # Diagnose configuration and hook problems
+teamai status                     # Show local vs team differences
+teamai list                       # List resources (skills|rules|docs|env|agents|hooks|mcp)
+teamai members                    # See team members (subcommand: teamai members list)
+teamai roles                      # Manage roles / resource namespaces
+teamai projects                   # Manage multiple projects from one repo (list|set|members)
+teamai packages                   # Install team-declared npm packages & Claude plugins
+teamai env                        # Manage shared team environment variables
+teamai dashboard                  # Open the AI coding session dashboard (web UI, default port 3721)
+teamai contribute --file <p> --title <t>   # Contribute a knowledge doc (usually via the teamai-share-learnings skill)
+```
+
+Anything not in this cheat sheet: check `teamai <command> --help` before using it.
+Do **not** guess flags (for example, there is no member-invite flag in the CLI —
+inviting a member is done on the Git platform's website; see
+`references/manage-admin.md`).

package/skills/teamai/references/contribute-member.md

@@ -0,0 +1,100 @@
+# Scenario: Member — publish a reusable skill
+
+Goal: the user turns something they built into team knowledge everyone can pull.
+**Any member can do this — you do not need to be an admin.** The usual entry point
+is the user just asking in plain language, e.g. *"share this xxx skill with my
+team"* / *"把这个 xxx skill 分享给团队"* — then you run the publish for them.
+
+## Which kind of contribution?
+
+- **A learning** (a lesson, a gotcha, how you solved something) → this is
+  **automatic**: TeamAI prompts at the end of a session worth sharing and the
+  dedicated **`teamai-share-learnings`** skill takes over (it summarizes the
+  session and runs `teamai contribute`). The user does not come through this flow
+  for it. (Step A below is only a manual fallback for when that skill isn't
+  available.)
+- **A reusable skill** (a `SKILL.md` others invoke) → author the skill, then
+  `teamai push` (Step B — the main purpose of this reference).
+
+## Step A — Contribute a learning by hand (fallback only)
+
+> Prefer the **`teamai-share-learnings`** skill. Use these manual steps only if it
+> is unavailable in the current tool.
+
+1. Write a short Markdown doc that captures the lesson. Keep it concrete and
+   actionable — a knowledge base, not a diary. Include YAML frontmatter for search
+   indexing:
+
+   ```markdown
+   ---
+   title: "<short title of the problem or finding>"
+   author: <username>
+   date: <YYYY-MM-DD>
+   tags: [tag1, tag2, tag3]
+   ---
+
+   ## Background
+   What were you doing? What went wrong?
+
+   ## Solution
+   How did you fix it? Key steps.
+
+   ## Takeaways
+   - Lesson 1
+   - Lesson 2
+   ```
+
+2. Save it to a temp file, then push it to the team:
+
+   ```bash
+   teamai contribute --file /tmp/my-learning.md --title "K8s pod startup timeout"
+   ```
+
+The doc lands in the team's `learnings/` and appears for teammates on their next
+`teamai pull`. It is also searchable via `teamai recall`.
+
+> Tip: if there is a dedicated learnings skill available in this tool
+> (`teamai-share-learnings`), you can use it to auto-summarize the current session
+> instead of writing the doc by hand.
+
+## Step B — Contribute a reusable skill
+
+1. Create the skill directory with a `SKILL.md`:
+
+   ```
+   skills/my-skill/SKILL.md
+   ```
+
+   Minimal frontmatter:
+
+   ```markdown
+   ---
+   name: my-skill
+   description: "One line — what it does and when to use it"
+   ---
+
+   # My Skill
+
+   Step-by-step instructions the AI should follow.
+   ```
+
+2. Publish it:
+
+   ```bash
+   teamai push --skill skills/my-skill        # one skill
+   # or
+   teamai push                                # review and push everything
+   ```
+
+   To publish into a specific role namespace: `teamai push --skill <path> --role <id>`.
+
+## After contributing
+
+- Confirm it landed: `teamai list skills` (or `teamai status`).
+- Teammates receive it automatically on their next session, or via `teamai pull`.
+
+## If push is denied
+
+A permission error usually means you don't have write access to the team repo.
+Copy the exact error to your admin and ask them to grant access. (In read-only
+HTTP mode, `contribute` / `push` are not available — you can only consume.)

package/skills/teamai/references/join-member.md

@@ -0,0 +1,149 @@
+# Scenario: Member — join an existing team
+
+Goal: the user joins a team that already has a TeamAI repo. You need the team
+repo's **full URL** (the admin shares it). Do NOT create a new repo.
+
+Run the commands yourself. Only stop to ask when a step says "ASK".
+
+## Step 0 — Get the repo URL (REQUIRED — stop if missing)
+
+A member joins an **existing** repo. You need its full URL from the admin.
+
+If the user has not given a full URL, ask for it:
+*"Paste the full team repo URL your admin gave you (e.g.
+https://github.com/yourorg/yourrepo)."* Do not proceed with `owner/repo` short
+form.
+
+**If the user does not have the URL, STOP here.** Do not guess a URL, do not probe
+platforms, and — most importantly — **do not create a new repo.** Tell the user:
+*"Ask your team's TeamAI admin for the repository URL, then come back and paste it
+here."* A member without a repo URL cannot continue; creating one would fork the
+team into a second, empty repo. (Setting up a brand-new team repo is the admin
+flow — see `setup-admin.md` — not this one.)
+
+## Step 1 — Install and verify
+
+```bash
+npm install -g teamai-cli
+teamai --version
+```
+
+If it fails, Node.js ≥ 20 is missing — have them install Node 20+ first.
+
+## Step 2 — Choose scope (ASK)
+
+- **This project only** (default): `cd` into the project directory first.
+- **Whole machine**: add `--scope user`.
+
+## Step 3 — Log in to the same platform as the URL
+
+Match the login to the URL's host (do NOT create a second repo):
+
+- **`git.woa.com/...`** (Tencent TGit / 工蜂) → **you run both the `gf` install and
+  the `gf … auth login`** (never tell the user to run them). Use the exact
+  download/verify commands and login step from `setup-admin.md` (Step 3, Tencent
+  TGit). The user's only action is approving the login URL in their browser / iOA.
+  No `GITLAB_URL` needed. (Headless only: pre-set `TGIT_TOKEN`.)
+- **`cnb.cool/...`** → install the CNB CLI, then authorize, in this order:
+  1. `npm install -g @cnbcool/cnb-cli`
+  2. `cnb login` — have the user approve it in the browser (OAuth2 device flow);
+     wait until they confirm before continuing.
+- **`github.com/...`** → `gh auth login`
+- **`gitlab.com/...`** or self-hosted GitLab → set `GITLAB_TOKEN` (and `GITLAB_URL`
+  for self-hosted, with `api` scope)
+
+If they have no account on that platform, they register there, then ask the admin
+to add them to the repo.
+
+## Step 4 — Initialize with the URL (you run it)
+
+```bash
+# this project only (run from inside the project)
+teamai init https://<platform>/<org>/<repo>
+
+# or whole machine
+teamai init https://<platform>/<org>/<repo> --scope user
+```
+
+**Set up all their AI tools by default (global rule 9).** Don't add `--agent` to
+restrict the install unless the user said to. Omitting it gives a picker — select
+**every AI tool already installed**. Afterwards, **tell the user (in their
+language) which agents will now auto-sync TeamAI**, and note any detected tool that
+was skipped and why.
+
+**Read-only / restricted environments (no Git access):** some sandboxed hosts
+cannot use Git. If the admin provides an HTTP endpoint + API key instead, use:
+
+```bash
+teamai init --http https://your-team-host/api --token <api-key>
+```
+
+This is a read-only consumer mode — `push` / `contribute` are not available, but
+skills and rules still sync.
+
+## Step 5 — Verify with doctor
+
+```bash
+teamai doctor
+teamai hooks list      # per-tool: which AI tools actually got the hooks
+```
+
+Fix anything `doctor` reports. **Do not trust the "Hooks injected into all AI tool
+settings" message alone** — it prints even for tools where nothing was written.
+Check the real per-tool status with `teamai doctor` / `teamai hooks list`. Only the
+tool you set up (e.g. `claude`) is expected to show hooks installed; some tools are
+skipped by design or not yet supported (CLI behaviour, not a broken setup). If it
+flags hook problems, load `troubleshooting.md` ("Which tools actually get hooks").
+
+## Step 6 — Confirm the skills actually arrived
+
+Team resources sync on **session start**, so they may be empty right after init.
+To confirm now:
+
+```bash
+teamai pull        # sync immediately
+teamai list        # see the team skills / rules / docs you now have
+```
+
+Then tell the user: from now on, **opening a new session in this AI tool
+auto-syncs** the latest team resources — no manual step needed. If their tool has
+no session-start hook (e.g. Gemini CLI, JoyCode), they run `teamai pull` by hand.
+
+**Reassure them about privacy** (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 joined — usage counts and knowledge you choose to contribute, never
+your raw conversation content."* (Team reporting is opt-in and carries counts +
+tool names only, on a separate branch of that same repo.)
+
+## Agent-specific note
+
+If this conversation is running in **ChatGPT App** or **WorkBuddy**, the hooks
+that drive auto-sync need an extra manual step — load `troubleshooting.md`
+("Agent-specific caveats") and walk the user through it before finishing.
+
+## If something is denied
+
+Permission errors (can't clone, can't read) usually mean the admin has not added
+this user to the repo yet. Have them copy the exact error message to their admin.
+
+## Wrap up in the user's language, and how to leave
+
+Summarize the outcome **in the user's own language** (global rule 1). Cover:
+
+1. **They're done — sync is automatic.** From now on, opening a session in this AI
+   tool keeps their team skills up to date; no commands needed.
+2. **Sharing a session learning is automatic — no command to remember.** When a
+   session produced something worth sharing, TeamAI **prompts them on its own** (at
+   the end of the session) and the `teamai-share-learnings` skill takes over to
+   summarize and contribute it. They do **not** invoke `/teamai` for this. (This
+   prompt only appears if the admin left team sharing enabled — it is on by
+   default; the admin can turn it off in `teamai.yaml`.)
+3. **They can also contribute a skill — just ask in plain language.** A member does
+   not need to be an admin to publish a skill. They tell TeamAI something like
+   *"share this xxx skill with my team"* / *"把这个 xxx skill 分享给团队"*, and you
+   run the publish for them (see `contribute-member.md`).
+4. **How to leave — via the skill, not raw commands.** They can remove TeamAI any
+   time by re-invoking the skill; you'll run it for them:
+   `/teamai 卸载` / `/teamai Uninstall TeamAI`.
+   One line, in their language: *"This only removes things from your machine; the
+   team repo stays — rejoin any time with `/teamai` and the repo URL."*

package/skills/teamai/references/manage-admin.md

@@ -0,0 +1,148 @@
+# Scenario: Admin — day-to-day management
+
+The user already ran `teamai init`. Do NOT re-init or re-register. Before changing
+anything, say what you are about to change. Pick the task below that matches.
+
+Day-to-day management is mostly **publishing and updating team resources — skills,
+rules, MCP servers, and env** — plus inviting members and checking the dashboard.
+
+## Publish or update a skill / rule / doc
+
+The user (or you) creates or edits a skill, rule, or doc locally, then publishes it
+to the team. The same `teamai push` handles both new resources and updates to
+existing ones:
+
+```bash
+teamai push            # review the diff, then confirm
+teamai push --all      # push everything without per-item confirmation
+teamai push --skill <path>   # push one specific skill
+```
+
+Members receive it automatically the next time they open a session (or when they
+run `teamai pull`).
+
+## Publish or update team MCP servers
+
+```bash
+teamai mcp list        # team MCP servers + per-tool install status
+teamai mcp inject      # push team MCP servers into every AI tool's config
+teamai mcp remove      # remove teamai-managed MCP servers
+```
+
+MCP definitions travel with the team repo like skills/rules — edit, then the
+members pick them up on sync.
+
+## Invite a member
+
+There is **no CLI invite flag.** Inviting is done on the Git platform's website:
+
+1. On the platform (GitHub / GitLab / CNB), add the person to the team repo
+   (Settings → Collaborators / Members).
+2. Send them the **full repo URL** and this line to paste into their AI tool:
+   `/teamai Help me join my team's TeamAI, repo URL is <URL>`
+
+(If you want to see who is already registered: `teamai members` /
+`teamai members list`.)
+
+## See members and resources
+
+```bash
+teamai members list          # registered team members
+teamai list                  # all resource types
+teamai list skills           # just skills
+teamai status                # local vs team differences
+```
+
+## Roles (skill namespaces per job function)
+
+```bash
+teamai roles list            # roles defined + your current role
+teamai roles init            # create the roles manifest (admin, interactive)
+teamai roles add <id>        # add a role
+teamai roles update <id>     # change a role's namespaces / description
+teamai roles remove <id>     # remove a role
+```
+
+After editing roles, `teamai push` to publish the manifest. Members re-sync on
+their next session.
+
+## Projects (manage several projects from one repo)
+
+`project` is a second dispatch dimension alongside `role` — one team repo can serve
+multiple projects, each with its own skills/rules/learnings, without a separate
+repo per project:
+
+```bash
+teamai projects list         # projects defined + the ones active in this directory
+teamai projects set <id>     # set the active project(s) for this directory
+teamai projects members <id> # who is registered on a project
+```
+
+A member gets the union of their role resources and their active project's
+resources. Admins declare projects in `manifest/projects.yaml`, then `teamai push`.
+
+## Team dashboard (web UI)
+
+```bash
+teamai dashboard             # start the AI coding session dashboard (default port 3721)
+teamai dashboard --port 8080 # custom port
+```
+
+Opens a local web UI for team coding-session activity and knowledge-base health.
+
+## Team packages (npm + Claude plugins)
+
+Declare packages once; members get a prompt to install them (TeamAI never runs
+third-party package code automatically):
+
+```bash
+teamai packages install typescript          # npm dependency
+teamai packages install eslint@latest --global   # global CLI tool
+teamai packages install code-review@claude-plugins-official   # Claude plugin
+teamai push                                 # share the updated teamai.yaml
+```
+
+## Shared environment variables
+
+```bash
+teamai env list              # list (values masked)
+teamai env list --reveal     # show values in plaintext
+teamai env add <KEY> <VALUE> # add or update
+teamai env remove <KEY>      # remove
+```
+
+## When sync fails
+
+Run `teamai doctor` first. If it reports hook or path problems, load
+`troubleshooting.md`. Have the affected member reopen their session; if their tool
+has no session-start hook, they run `teamai pull` manually.
+
+## Capture a lesson learned
+
+Turning a tricky fix into team knowledge is **automatic**: at the end of a session
+worth sharing, TeamAI prompts the member and the dedicated
+**`teamai-share-learnings`** skill summarizes the session and runs
+`teamai contribute`. Nobody has to invoke it by hand.
+(Publishing a **reusable skill** someone authored is a different task — any member
+can do it, see `contribute-member.md`.)
+
+### Turn the sharing prompt on or off (admin)
+
+The auto-share prompt is **on by default**. To disable it team-wide, set this in
+`teamai.yaml` and `teamai push`:
+
+```yaml
+sharing:
+  contributeHint:
+    enabled: false      # team-wide default; members can still override locally
+```
+
+Resolution order: `TEAMAI_CONTRIBUTE_HINT_DISABLED=1` env kill switch > a member's
+local override > this team setting > default (on). Turning it off here only removes
+the nudge; members can still contribute on request.
+
+## Don't
+
+- Don't hand-run raw `git` commands.
+- Don't create a second team repo.
+- Don't use `owner/repo` short form — always the full URL.