@team-ai/teamai-cli 0.22.10 → 0.30.1

package/skill-data/workflow/references/judging.md

@@ -0,0 +1,13 @@
+# Judging
+
+A run whose steps list scorers is judged on this machine when describe found the confined judge of your session's tool here and the person kept judging. TeamAI runs that judge in the background on each scored step's work, from evidence only the judge reads, so a label stays independent of the session whose work it scores. Your part is the person.
+
+| Event | What happened | Tell the person |
+|---|---|---|
+| `judging` | A judge started on the pass of `step` that `scorers` judge. | `step` is being scored. |
+| `judged` | `scorer` labelled the pass of `step` with `label`. | the step, the scorer and the label |
+| `judging-off` | Judging of this run stopped for `failure`, and nothing more of it is judged here. | `failure.message` |
+
+A `done` action that carries `judging` has a judge still open. Keep running `then` until a turn has none: each `judged` event comes in one of those turns.
+
+The person opts out of judging before the run starts, by picking a `without judging` option of the describe question. A run keeps the judging it started with.

package/skill-data/workflow/references/places.md

@@ -0,0 +1,32 @@
+# Places your host makes
+
+On `h3`, your host makes the worktree a prompt step works in, and TeamAI adopts it. TeamAI owns the contract: the branch, the commit it starts from, and the checks the place must pass. Your host owns the place. A `place` action asks for the place of one step, for each `attempt`:
+
+1. Have your host make a worktree of this repository named `name`, on branch `branch` from commit `start`. When your host takes only a starting point, make it detached at `start`: TeamAI creates `branch` there when it adopts it.
+2. Run `adopt` with the worktree's absolute directory in place of `{dir}`. The slot sits inside single quotes, so write each `'` in that directory as `'\''`.
+3. Act on the turn it returns:
+   - A `dispatch` for the same `attempt`: start the child in that worktree, as the workflow skill's Dispatch section says. Its `dir` is the place.
+   - The `place` action again, with `refused`: the place was not adopted, and `refused` says why and what to fix. Fix that place or make another, then run `adopt` again. The step keeps waiting, and a refusal costs it nothing.
+
+Done when the turn carries a `dispatch` for the `attempt`.
+
+When your host makes a worktree only as it starts a child there, start that child first and tell it to wait for its task. Adopt the worktree it got, then send it the dispatch's prompt as its task.
+
+## The checks
+
+`adopt` checks the place before it changes anything there. The place must be:
+
+- the top directory of a worktree of the run's repository, as `git worktree add` in this checkout makes; a separate clone does not count;
+- clean: no uncommitted or untracked changes;
+- on `branch`, or detached at `start` while `branch` does not exist yet;
+- holding `start` in its history;
+- left by no setup that failed or was cut short there: remove that worktree and make it again;
+- free: no other open step of the run works there.
+
+A step that was stopped leaves its edits in its place for your host to keep or drop. Commit, stash or remove them before you adopt that place again.
+
+## Later steps
+
+A later step on the same branch, a command or a read-only step included, goes on in the place the last step on it finished in, while that place passes the checks: a prompt's dispatch comes with that `dir`, and no `place` action. When the place no longer passes, because your host removed it or it has changes, a `place` action asks for another.
+
+TeamAI commits each step's work in the place and never removes it. Remove it with your host once the run is done.

package/skill-data/workflow/references/sandbox.md

@@ -0,0 +1,14 @@
+# Children in a sandbox or VM
+
+Read this when your host starts child agents inside a sandbox, a container or a VM, rather than as processes that share this machine's files.
+
+A child changes code only in a place TeamAI prepared or checked: TeamAI commits, pushes and cleans up there with git and the team's delivered files. So the place has to be one that the `teamai` you run can reach.
+
+1. Find where your children's files live:
+   - **This machine's filesystem.** The child sees the `dir` its dispatch names. Answer the host question by how your host starts children. The sandbox changes nothing.
+   - **Inside the sandbox only.** The child cannot see `dir`, and TeamAI adopts only a worktree of this checkout, so this session cannot run the steps that change code. Tell the person that `teamai workflow cancel <run>` ends this run, and that the local driver can run the workflow from their terminal or CI, as `teamai skill get workflow-local` describes.
+2. Run the option's `run`.
+
+Done when the turn it returns has no `choose` action, or the person has the local-driver route.
+
+A worktree is not a sandbox. TeamAI declares no isolation for a skill run, so a step whose workflow requires `isolation: sandbox` still runs, and its `unenforced` lists `isolation`. Its dispatch carries `needs.isolation: sandbox`: start that child in a sandbox when your host has one that sees `dir`, and otherwise tell the person the step ran without one. Tell the person a step ran sandboxed only when your host says so.

package/skill-data/workflow-local/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: workflow-local
+description: Run a team workflow unattended with the local driver. Use in CI or a cloud agent, when a describe reply routed the run to the local driver, or to continue a run on this machine without a coding session.
+---
+
+# Run a team workflow unattended
+
+The local driver runs a whole run in one process on this machine: each command step as a process, each prompt step through a headless tool. Nobody is asked anything while it runs, so every answer the run needs is decided before it starts.
+
+## When
+
+- A CI job or a cloud agent runs the workflow.
+- `teamai workflow start --describe <name> --driver skill` answered `ask.kind: local`: a coding session cannot run some step, and `ask.reason` says which.
+- A run continues on this machine without a coding session: after a retry, an answer, a stopped driver, or a session that handed it over.
+
+## Run it
+
+1. Run `teamai workflow start <name> --describe` and read the inputs it lists.
+2. Start the run: `teamai workflow start <name> --driver local`, with the inputs as one JSON object in `--inputs`. `teamai workflow start --help` lists the other options, such as answering optional approvals and picking the prompt tool.
+3. To continue a run that stopped, run `teamai workflow resume <run>`.
+
+The command exits when the run ends: 0 when it succeeded, 1 when it failed or was cancelled. Done when it has exited and the outcome, the failing step's message and the pull requests the run opened are reported where the person reads them: the job log, or your reply.
+
+## Approvals
+
+Without a terminal, nobody answers a gate during the run:
+
+- A required approval fails its step `hitl_required`, and so does the run.
+- With `--auto-approve`, or the member's `workflows.auto_approve`, an optional approval is answered yes and a choice takes its default.
+- Without either, an optional approval is skipped, and a choice fails `hitl_required`.
+
+## From an agent session
+
+A coding agent's session may start or continue only a workflow whose `invoke` allows it, with `start` or `resume`. `invoke: allow` goes on. `invoke: ask` goes on once the person agreed, with `--confirmed`, and never in an unattended run (CI or a cloud agent), where it answers `unattended_denied`. `invoke: deny`, the default, answers `invoke_denied`. Tell the person the `message`, which names the command for their own terminal.
+
+Inside a workflow step, every `teamai workflow` command that changes a run answers `nested_workflow`. Do the step's own work there instead.
+
+## Env and secrets
+
+A step gets the team env keys its `requires.env` lists, and no other team key. A key with no value on this machine fails the step `missing_env` before it runs, and the message names the `teamai env set` command. A CI job exports each secret under its key name instead. TeamAI masks the value of every key in `env/secrets.yaml` in run files and output.
+
+## CI
+
+When you set up a CI job that starts a run, read `references/ci.md`.

package/skill-data/workflow-local/references/ci.md

@@ -0,0 +1,16 @@
+# Start a run from CI
+
+The guide has the GitHub Actions job to copy: [Start from CI](https://github.com/Tencent/teamai-cli/blob/main/docs/guide/workflow.md#start-from-ci). It checks out a named branch, runs `teamai init` and `teamai pull`, then `teamai workflow start <name> --driver local`.
+
+Two settings in that job decide whether the run works:
+
+1. **The teamai version.** teamai before 0.28.0 drops a workflow that sets `invoke` or `alias`, so the job finds nothing to run. Pin `teamai-cli` at 0.28.0 or later.
+2. **The token.** It reads the team repo, pushes branches to the product repo, and opens pull requests there, which a `deliver: pr` step needs. The default GitHub Actions token cannot read another repository.
+
+A CI job sets `CI`, which makes the run unattended, and every process of its steps gets `TEAMAI_MODE=unattended`. A scheduler that sets no `CI`, such as cron, makes the run unattended itself:
+
+```yaml
+env: { TEAMAI_MODE: unattended }
+```
+
+Done when the job pins that version and its token has those three permissions.

package/skills/teamai/SKILL.md

@@ -11,7 +11,7 @@ description: >-
   after a friction reminder. Triggers include "set up teamai", "join the team repo", "sync team
   skills", "team wiki", "share what I learned", and running /teamai. Talking about a team needs no
   skill; operating on what the team shares does.
-allowed-tools: Bash(teamai skill:*), Bash(npx teamai-cli skill:*)
+allowed-tools: Bash(teamai skill:*), Bash(npx teamai-cli skill:*), Bash(teamai workflow start --describe:*), Bash(teamai workflow next:*), Bash(teamai workflow report:*), Bash(teamai workflow respond:*), Bash(npx teamai-cli workflow start --describe:*), Bash(npx teamai-cli workflow next:*), Bash(npx teamai-cli workflow report:*), Bash(npx teamai-cli workflow respond:*)
 ---
 
 # teamai
@@ -37,6 +37,8 @@ The CLI serves skill content that always matches the installed version, so instr
 teamai skill get setup            # day 0: create a team repo (admin) or join one (member), manage, uninstall
 teamai skill get wiki             # large multi-repo codebase: architecture reverse-engineering and knowledge base
 teamai skill get share            # turn what this session taught you into a team learning (needs recall on)
+teamai skill get workflow         # drive a requested team workflow from this coding session
+teamai skill get workflow-local   # run a workflow unattended: CI, cloud agents, a handed-off run
 ```
 
 Publishing a skill, rule or doc the user already has is in `core`; it needs no recall.