testeiya 0.6.0 → 0.8.0

package/PIPELINES.md

@@ -0,0 +1,332 @@
+# Pipeline file format
+
+A pipeline is a QA flow in one YAML file: agent tasks and shell commands, run in
+order, passing files through one folder. One command runs it:
+
+```bash
+testeiya pipeline <name|path.yml> [options]
+```
+
+This page is the reference for the file. The [README](README.md#pipelines) shows
+how to use pipelines in CI.
+
+## A complete example
+
+```yaml
+name: regression
+description: Run the tests a change can break, then explain the failures.
+
+summary: |
+  Lead with failures this change caused. Flaky tests go last.
+
+env:
+  BASE_BRANCH: ${BASE_BRANCH:-origin/main}
+
+gates:
+  coverage:
+    file: [coverage.tests.yml]
+    message: No coverage.tests.yml. Create one with /qa-test-code-coverage.
+  testomatio:
+    env: [TESTOMATIO]
+    message: No Testomat.io project. Set TESTOMATIO to the project's API key.
+  local:
+    run: test -z "$REMOTE"
+    message: Tests run on the Testomat.io CI profile. No local log to read.
+  test-command:
+    env: [TEST_COMMAND]
+    message: No test command. Set TEST_COMMAND, e.g. "npx playwright test".
+
+when: [coverage]
+
+stages:
+  - id: tests
+    when: [testomatio]
+    run: |
+      npx -y @testomatio/reporter run --kind detect --warn \
+        --filter "coverage:file=coverage.tests.yml,diff=$BASE_BRANCH" \
+        ${REMOTE:+--remote "$REMOTE"} ${TEST_COMMAND:+"$TEST_COMMAND"}
+    timeout: 30m
+
+  - id: failures
+    when: [local, test-command]
+    session: triage
+    task: |
+      Read the test run in tests.log. For each failure, say if this change caused it,
+      if it is flaky, or if the test is out of date. /debug-fix-failed-flaky-autotests
+      Fail the run if this change caused a failure.
+    inputs: [tests.log]
+```
+
+## Top level
+
+| Key | Required | Meaning |
+|---|---|---|
+| `name` | no | Shown in logs and `pipeline.json`. Default: the file name |
+| `description` | no | One line, shown by `testeiya pipeline` |
+| `summary` | no | Extra instructions for the final summary |
+| `env` | no | Variables for every stage. Values expand `${NAME}` |
+| `gates` | no | Named checks, defined once. See [Gates](#gates) |
+| `when` | no | Gates for the whole run. One fails: nothing runs, exit 0 |
+| `stages` | yes | The stages, run in order. At least one |
+
+An unknown key is an error, found before anything runs.
+
+## Stages
+
+| Key | Meaning |
+|---|---|
+| `id` | Required. Lowercase words joined by dashes. Unique. Names the stage's files. `pipeline` and `summary` are reserved |
+| `task` | An agent stage: the task text. `/skill` names expand |
+| `run` | A command stage: a shell command, run with `sh` in the checkout |
+| `when` | Gates this stage needs. One fails: the stage is skipped with its message |
+| `session` | A named, persistent conversation. See [Sessions](#sessions) |
+| `inputs` | Files the stage reads, from the pipeline folder |
+| `outputs` | Files the stage must leave in the pipeline folder |
+| `each_line` | Run once per non-empty line of this file. See [Loops](#loops) |
+| `each_file` | Run once per file matching this mask |
+| `stopOn` | `fail`, `gate`, or both as a list. See [Stopping](#stopping) |
+| `timeout` | `90s`, `30m`, `1h`, or seconds. Per item in a loop. Default: none |
+
+- A stage has exactly one of `task` or `run`.
+- A stage has at most one of `each_line` or `each_file`.
+- A list key also takes a single value: `when: staging` is `when: [staging]`.
+- Explorbot, the reporter and test runners are plain `run` commands. They have
+  no stage type of their own.
+
+## Gates
+
+A gate is a named check with a message. It is defined once under `gates:` and
+named in `when:`, at the top level or in a stage.
+
+```yaml
+gates:
+  staging:
+    env: [EXPLORBOT_URL]
+    message: No staging URL. Set EXPLORBOT_URL to test in a browser.
+```
+
+| Check | Passes when |
+|---|---|
+| `env: [A, B]` | every variable is set and not empty |
+| `file: [path]` | every path exists, relative to the checkout |
+| `run: <command>` | the command exits 0 within 30 seconds. Its output is hidden |
+| `changes: {…}` | the changed files match, see [Changes](#changes) |
+
+- A gate needs a `message` and at least one check. All its checks must pass.
+- Every gate is checked once, before the first stage. `--dry-run` prints them all.
+- A name in `when` that `gates` does not define is an error.
+- `ai` is built in: a model and a provider key resolve. The summary needs it, so
+  a pipeline without one exits 2 before anything runs.
+
+### Gates from the CI job
+
+The job can add a gate without editing the file:
+
+```bash
+testeiya pipeline regression --gate 'pr:test -n "$PR_NUMBER"'
+```
+
+- `--gate NAME:COMMAND` splits on the first colon. It is a `run` gate added to
+  the top-level `when`.
+- When it fails the whole run is skipped and exits 0.
+- It is checked before `--output`, so `-o "gh:pr#$PR_NUMBER"` is fine when the
+  number only exists when the gate passes.
+- A name the file already defines is an error.
+
+### Checking a pipeline
+
+```bash
+testeiya pipeline-check regression --set TEST_COMMAND="npx playwright test"
+```
+
+- Validates the file the way a run does, then checks every gate it declares,
+  used or not, plus `ai` and any `--gate`.
+- Prints each gate as passed or not, with its `message` when it does not pass.
+- Runs no stage and spends no tokens. Takes `--set`, `--gate`, `--dir`, `--model`
+  and `--json`.
+- Exit code: `0` every gate passes, `1` one does not, `2` the file is invalid.
+- `--diagram` also writes `<name>.diagram.md` to the current folder: a Mermaid
+  chart of the stages in order, the files they pass on (dotted), and the gates
+  each one needs, green when it passes and red when it does not.
+
+### Changes
+
+```yaml
+gates:
+  api-changed:
+    changes:
+      paths: ["src/api/**", "openapi.yaml"]   # at least one changed file matches
+      ignore: ["**/*.md", "**/*.lock"]        # these never count
+      min_files: 3                            # at least this many count
+    message: No API code changed.
+```
+
+Every key is optional. All given must hold, and at least one file must count.
+
+- First round: the diff from the merge base with the target branch. The branch
+  comes from `GITHUB_BASE_REF`, `CI_MERGE_REQUEST_TARGET_BRANCH_NAME`,
+  `BITBUCKET_PR_DESTINATION_BRANCH`, then `BASE_BRANCH`, then `origin/main`.
+- Later rounds: the diff since the commit the last round ran on.
+- Git cannot say (a shallow clone): a pipeline that uses `changes` exits 2.
+  Check out with `fetch-depth: 0`.
+- The list is written to `changes.txt` in the pipeline folder.
+
+## Variables
+
+- `${NAME}` and `${NAME:-default}` expand in `task`, `env`, `outputs` and gate
+  values. Unset is empty. `run` goes to the shell, which uses the same rules and
+  more, like `${NAME:+word}`.
+- `--set KEY=VALUE` and the job's own environment reach every stage. `--set` wins
+  over `env:`.
+- The runner sets:
+
+| Variable | Value |
+|---|---|
+| `PIPELINE_DIR` | absolute path of the pipeline folder |
+| `PIPELINE_NAME` | the pipeline's name |
+| `PIPELINE_ROUND` | 1, 2, … |
+| `ITEM` | in a loop: the line, or the file's path |
+| `ITEM_NAME` | in an `each_file` loop: the file name without its extension |
+| `PIPELINE_RESUME` | `1` when a command stage is retried |
+
+`TESTEIYA_FOLLOW_UP`, `TESTEIYA_THREAD` and `TESTEIYA_SESSION_FILE` are removed:
+they belong to a single task.
+
+## Files
+
+Every stage runs in the checkout. Paths in `inputs`, `outputs` and loops resolve
+against the pipeline folder, `$PIPELINE_DIR`. A path ending in `/` is a folder.
+
+Each stage leaves its own files:
+
+| File | Stage | Content |
+|---|---|---|
+| `<id>.md` | agent | the stage's report |
+| `<id>.json` | agent | status, reason, tokens, session id |
+| `<id>.log` | command | stdout and stderr |
+
+- A later stage reads them by name: `inputs: [review.md]`.
+- An `outputs` entry may not reuse one of these names.
+- Every input must come from an earlier stage, from the runner (`changes.txt`),
+  or exist in the folder at start.
+- After a stage, every `outputs` entry must exist, or the stage is `broken`.
+- An agent stage's task gets a block that names the folder, the files to read,
+  the files to write, and inputs a skipped stage did not produce.
+- A command stage whose inputs all come from skipped stages is skipped too. An
+  agent stage still runs and is told what is missing.
+
+## Loops
+
+```yaml
+- id: explore
+  each_line: endpoints.txt
+  run: npx -y explorbot api explore "$ITEM"
+
+- id: sync
+  each_file: test-cases/*.md
+  task: Sync ${ITEM} to Testomat.io. /sync-test-cases-with-tms
+```
+
+- `each_line` runs once per non-empty line. `each_file` runs once per matching
+  file, sorted, with `*` and `**`.
+- Both resolve against the pipeline folder and are matched when the stage
+  starts, so earlier stages can write them.
+- Nothing to loop over: the stage is skipped.
+- Items run one after another. A failed item does not stop the others. The stage
+  takes the worst item's status.
+- Each item writes `<id>.1.md`, `<id>.2.md`, … or `<id>.1.log`, …, joined into
+  `<id>.md` or `<id>.log` at the end.
+- An agent loop with a `session` runs every item in that conversation.
+
+## Sessions
+
+- `session: <name>` keeps the conversation in `.sessions/<name>.jsonl` in the
+  pipeline folder.
+- Stages with the same name share one conversation. Different names never see
+  each other's reasoning, only each other's files.
+- No `session`: a fresh conversation, saved nowhere.
+- A session lasts as long as the folder. Kept between rounds, a stage on round 2
+  continues its round 1 work.
+
+## The summary
+
+A pipeline with more than one stage ends with a summary. It is not written in
+the file: the runner adds it.
+
+- It runs the `pipeline-report` skill with the `summary:` text, reads every
+  stage's files, and writes `summary.md`.
+- Its report is the only thing sent to `--output`. Every other stage runs with
+  `--no-thread` and posts nothing.
+- It explains the pipeline's verdict and never changes it.
+- It runs after the last stage, and after a stage that stopped the pipeline. Not
+  after Ctrl-C, and not when the run was skipped.
+- A one-stage pipeline has no summary. That stage's report is the report.
+
+## Stopping
+
+| Status | Agent stage | Command stage |
+|---|---|---|
+| `pass` | verdict pass | exit 0 |
+| `fail` | verdict fail | non-zero exit |
+| `broken` | crashed, or an `outputs` file is missing | an `outputs` file is missing |
+| `timeout` | ran past `timeout` | same |
+| `skipped` | a gate in `when` failed, or nothing to loop over | same, or its inputs were skipped |
+| `not-run` | an earlier stage stopped the pipeline | same |
+
+- `broken` and `timeout` always stop the pipeline.
+- `stopOn: fail` stops it when this stage fails.
+- `stopOn: gate` stops it when this stage is skipped by a gate.
+
+Exit code: `0` pass or skipped, `1` any fail, broken or timeout, `2` bad usage
+or no AI provider, `130` interrupted. `--exit-zero` forgives `fail` only.
+
+## Rounds
+
+Without `--dir` a pipeline runs once in a temp folder. Keep `--dir` between
+runs, as a CI cache per pull request, and each run is a round:
+
+| Folder holds | Same commit | New commit |
+|---|---|---|
+| nothing | round 1 | round 1 |
+| a stopped round | retry from the stage that stopped | new round |
+| a finished round | the same round again | new round |
+
+- A retry keeps stages that passed or failed and uses the folder's copy of the
+  file, so the stages cannot change half-way.
+- A new round clears the last round's files, keeps `.sessions/`, and counts
+  `changes` from the last round's commit. Stages with a session are told what
+  changed. The summary updates its comment.
+- `--dir` may not be the checkout or a folder above it.
+
+`pipeline.json` in the folder holds the round, each stage's status and the
+round history. `--json` prints it.
+
+## In CI
+
+Find what only the job knows in a step of its own, then run the pipeline in one
+command:
+
+```yaml
+- name: Find pull request
+  env:
+    GH_TOKEN: ${{ github.token }}
+  run: |
+    gh api "repos/$GITHUB_REPOSITORY/commits/$GITHUB_SHA/pulls" \
+      --jq '.[0] // empty | "PR_NUMBER=\(.number)\nPR_TITLE=\(.title)\nPR_URL=\(.html_url)"' \
+      >> "$GITHUB_ENV"
+
+- name: Run regression
+  env:
+    TESTOMATIO: ${{ secrets.TESTOMATIO }}
+    GH_TOKEN: ${{ github.token }}
+    OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+    TESTEIYA_MODEL: openrouter/anthropic/claude-haiku-4.5
+  run: |
+    npx -y testeiya@latest pipeline regression \
+      --gate 'pr:test -n "$PR_NUMBER"' \
+      --set REMOTE=github \
+      --set BASE_BRANCH=${{ github.event.before }} \
+      --set "TESTOMATIO_TITLE=PR #$PR_NUMBER $PR_TITLE" \
+      --set "TESTOMATIO_DESCRIPTION=$PR_URL" \
+      -o "gh:pr#$PR_NUMBER"
+```

package/README.md

@@ -81,6 +81,7 @@ testeiya models anthropic   # list what your key can reach
 ```bash
 testeiya task "<task>"     # run one task, deliver a report, exit
 testeiya ask "<question>"  # answer a question, no report
+testeiya pipeline <name>   # run several stages in a row, see Pipelines
 testeiya skills            # list the skills bundled with this package
 testeiya sessions          # list saved sessions for this folder
 ```
@@ -187,6 +188,117 @@ TESTOMATIO=tstmt_xxx testeiya task \
   --output audits/$(date +%F).md
 ```
 
+## Pipelines
+
+Some QA flows take more than one run, and not every step is the agent: review a
+pull request, run Explorbot against staging, then explain what broke. A
+pipeline is that flow in one YAML file, run by one command.
+
+```bash
+testeiya pipeline                     # list the bundled pipelines
+testeiya pipeline web-testing -o gh:pr-comment
+testeiya pipeline .github/testeiya/my-flow.yml --dry-run
+testeiya pipeline-check .github/testeiya/my-flow.yml   # check the file and every gate
+testeiya pipeline-check regression --diagram           # also draw it as a Mermaid chart
+```
+
+| Pipeline | What it does |
+|---|---|
+| `pr-review` | requirements, QA review, test cases, sync to Testomat.io |
+| `issue-test-cases` | an issue or epic, with its sub-issues, becomes test cases; set `ISSUE_URL` |
+| `web-testing` | review, an Explorbot plan, `explorbot test`, what broke |
+| `api-testing` | review lists changed endpoints, Explorbot tests each one |
+| `regression` | runs the tests `coverage.tests.yml` maps to the change, explains failures |
+
+To change one, copy it from `pipelines/` into your repo, edit it, and pass the
+path.
+
+### The file
+
+```yaml
+name: web-testing
+description: Review a pull request, test it in a browser, explain what broke.
+
+gates:
+  staging:
+    env: [EXPLORBOT_URL]
+    message: No staging URL. Set EXPLORBOT_URL to test in a browser.
+  browser:
+    run: ls "${PLAYWRIGHT_BROWSERS_PATH:-$HOME/.cache/ms-playwright}" | grep -q chromium
+    message: No browser. Run npx playwright install --with-deps chromium.
+
+env:
+  EXPLORBOT_OUTPUT: ${PIPELINE_DIR}/explorbot
+
+stages:
+  - id: review
+    session: qa
+    task: Review this pull request. Write browser scenarios to plan.md. /explorbot-plan
+    outputs: [plan.md]
+  - id: explore
+    when: [staging, browser]
+    run: npx -y explorbot test "$PIPELINE_DIR/plan.md" '*'
+    timeout: 30m
+  - id: results
+    session: qa
+    task: Read the Explorbot report under explorbot/ and say what broke.
+    inputs: [explorbot/]
+```
+
+- A stage is a `task` for the agent or a `run` shell command.
+- Stages pass files through one folder, `$PIPELINE_DIR`. An agent stage writes
+  `<id>.md` and `<id>.json`, a command writes `<id>.log`. `inputs` and
+  `outputs` name the rest.
+- `gates` are named checks: `env`, `file`, `run`, or `changes` (`paths`,
+  `ignore`, `min_files`). `when:` names the gates a stage needs. One fails and
+  the stage is skipped with its message. In the top-level `when:` it skips the
+  whole run.
+- `session: <name>` keeps a conversation. Stages with the same name share it.
+  No `session` is a fresh one.
+- `each_line: file.txt` and `each_file: cases/*.md` run a stage once per item,
+  as `$ITEM`.
+- `stopOn: fail` stops the pipeline when the stage fails, `stopOn: gate` when it
+  was skipped. A broken or timed-out stage always stops it.
+
+The full format is in [PIPELINES.md](PIPELINES.md).
+
+A pipeline with more than one stage ends with a summary written by the
+`pipeline-report` skill. It is the only thing posted to `--output`. Every other
+stage runs with `--no-thread`, so nothing else touches the pull request.
+
+### Rounds
+
+Keep `--dir` between runs, as a CI cache per pull request, and each run is a
+round. A re-run on the same commit retries from the stage that stopped. A new
+commit starts a new round: `changes` count from the last round's commit, stages
+with a session are told what changed, and the summary updates its comment.
+
+```yaml
+- uses: actions/cache/restore@v4
+  with:
+    path: ${{ runner.temp }}/qa
+    key: qa-pr-${{ github.event.number }}-${{ github.run_id }}
+    restore-keys: qa-pr-${{ github.event.number }}-
+- run: npx testeiya@latest pipeline pr-review --dir ${{ runner.temp }}/qa -o gh:pr-comment --exit-zero
+- uses: actions/cache/save@v4
+  if: always()
+  with:
+    path: ${{ runner.temp }}/qa
+    key: qa-pr-${{ github.event.number }}-${{ github.run_id }}-${{ github.run_attempt }}
+```
+
+Stages ignore `TESTEIYA_FOLLOW_UP`, `TESTEIYA_THREAD` and `TESTEIYA_SESSION_FILE`:
+those belong to a single task. Use `--thread` on the pipeline instead.
+
+`--set KEY=VALUE` sets a variable for every stage. `--gate NAME:COMMAND` adds a
+check from the CI job: when the command fails, the whole run is skipped and exits
+0, before any output is checked. Use it for what only the job knows, like
+whether this push belongs to a pull request. `--dry-run` prints every
+gate and stage and spends nothing. `testeiya pipeline-check` checks the file and
+every gate it declares, used or not, and prints the message of each one that
+does not pass. `--diagram` also writes the pipeline as a Mermaid chart.
+`pipeline.json` in the folder holds each stage's status; `--json` prints it.
+
 ## CI setup
 
 Testeiya needs three things in any CI system: a provider key, a model name, and
@@ -394,7 +506,8 @@ testeiya task "<task>" --output report.md --output run.json --output gh:pr-comme
 | `gh:pr#123` | posted on that pull request |
 
 Posting uses the GitHub CLI and resolves the PR number from `GITHUB_EVENT_PATH`,
-`GITHUB_REF`, or `gh pr view` — so inside Actions it just works. Every
+`GITHUB_REF`, or `gh pr view`. On a push with no PR of its own, like a merge to
+main, it posts on the PR that brought the commit in. Inside Actions it just works. Every
 destination is checked before the run starts, so a missing `gh` costs no tokens.
 
 `--footer "<text>"` adds a line under the report and `--header "<text>"` adds

package/dist/prompt/testomat.io.js

@@ -37,11 +37,11 @@ export function testomatio(options) {
 }
 function dynamicData(tms) {
     if (tms === "mcp-proxy") {
-        return "Get them through the `mcp` tool: search it for the operation you need, then call that operation. The most common reads are also registered as tools of their own; use those directly when they fit.";
+        return "Get them through the Testomat.io tools, one per entity (`tests`, `runs`, `testruns`, `issues`, …); pick the operation with its `command` param. The `mcp` tool searches them when the name is unclear.";
     }
     if (tms === "cli-only") {
         return "There are no Testomat.io tools in this session. Get them from the REST API: `curl` with the `TESTOMATIO` token as the Authorization header against `$TESTOMATIO_URL/api/v2`. Keep to documented endpoints; never invent paths or parameters.";
     }
-    return "Get them through the `testomatio-<slug>` MCP tools, one set per project.";
+    return "Get them through the `testomatio-<slug>` MCP tools, one set per project and one tool per entity; pick the operation with its `command` param.";
 }
 //# sourceMappingURL=testomat.io.js.map

package/dist/prompt/testomat.io.js.map

@@ -1 +1 @@
-{"version":3,"file":"testomat.io.js","sourceRoot":"","sources":["../../prompt/testomat.io.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,OAA0B;IACnD,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QACvB,OAAO,MAAM,CAAA;;;;;;;KAOZ,CAAC;IACJ,CAAC;IAED,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,IAAI,OAAO,CAAC,UAAU;QAAE,GAAG,GAAG,OAAO,OAAO,CAAC,UAAU,KAAK,CAAC;IAC7D,OAAO,MAAM,CAAA;;;;;6FAK8E,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC;;;;;;;;8IAQyB,GAAG;;GAE9I,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,GAAc;IACjC,IAAI,GAAG,KAAK,WAAW,EAAE,CAAC;QACxB,OAAO,qMAAqM,CAAC;IAC/M,CAAC;IACD,IAAI,GAAG,KAAK,UAAU,EAAE,CAAC;QACvB,OAAO,8OAA8O,CAAC;IACxP,CAAC;IACD,OAAO,0EAA0E,CAAC;AACpF,CAAC"}
+{"version":3,"file":"testomat.io.js","sourceRoot":"","sources":["../../prompt/testomat.io.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,OAA0B;IACnD,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QACvB,OAAO,MAAM,CAAA;;;;;;;KAOZ,CAAC;IACJ,CAAC;IAED,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,IAAI,OAAO,CAAC,UAAU;QAAE,GAAG,GAAG,OAAO,OAAO,CAAC,UAAU,KAAK,CAAC;IAC7D,OAAO,MAAM,CAAA;;;;;6FAK8E,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC;;;;;;;;8IAQyB,GAAG;;GAE9I,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,GAAc;IACjC,IAAI,GAAG,KAAK,WAAW,EAAE,CAAC;QACxB,OAAO,wMAAwM,CAAC;IAClN,CAAC;IACD,IAAI,GAAG,KAAK,UAAU,EAAE,CAAC;QACvB,OAAO,8OAA8O,CAAC;IACxP,CAAC;IACD,OAAO,+IAA+I,CAAC;AACzJ,CAAC"}

package/dist/src/args.js

@@ -4,6 +4,7 @@ export const WELCOME = `
 
   testeiya task "analyze this pr and find inconsistencies"
   testeiya ask "is this feature ready"
+  testeiya pipeline web-testing
 
   testeiya doctor    check your setup
   testeiya --help    options and environment
@@ -14,6 +15,8 @@ export const USAGE = `testeiya, an AI testing agent
 Usage:
   testeiya task "<task>"      run one task and write a report
   testeiya ask "<question>"   answer a question
+  testeiya pipeline <name>    run a multi-stage pipeline, or list them with no name
+  testeiya pipeline-check <name>  check a pipeline file and its gates, run nothing
   testeiya doctor             check what a run would resolve
   testeiya models [pattern]   list the models your key can reach
   testeiya skills [pattern]   list the skills bundled with this package
@@ -35,8 +38,15 @@ Options:
       --header <text>        line added above the report
       --footer <text>        line added under the report
       --no-default-footer    do not sign the report
+      --no-thread            keep out of the comment thread: post nothing, read no comments
       --json                 machine-readable output
       --probe                doctor only: test the key with one request
+
+Pipeline options:
+      --dir <path>           the pipeline folder; keep it between runs for rounds
+      --dry-run              show gates and stages, spend no tokens
+      --set KEY=VALUE        set a variable for every stage, repeatable
+      --gate NAME:COMMAND    skip the whole run unless COMMAND exits 0, repeatable
   -h, --help                 show this
   -v, --version              show version
 
@@ -173,6 +183,28 @@ Skills
   loaded before the run, e.g. "/qa-thinking". A name we do not ship is left
   alone, so a stray "/word" in the task is just a word.
 
+Pipelines
+
+  A pipeline is several stages in one YAML file: agent tasks and shell commands,
+  run in order, passing files through one folder. "testeiya pipeline" lists the
+  bundled ones; pass a path to run your own.
+
+    testeiya pipeline web-testing -o gh:pr-comment
+    testeiya pipeline .github/testeiya/regression.yml --set TEST_COMMAND="npx playwright test"
+
+  --gate adds a check from the CI job, e.g. --gate 'pr:test -n "$PR_NUMBER"'.
+  When it fails the whole run is skipped and exits 0.
+
+  A stage whose gate fails is skipped with the gate's message. A final summary
+  reads every stage and is the only thing posted. Keep --dir between runs, as a
+  CI cache per pull request, and a re-run on the same commit retries from the
+  stage that stopped, while a new commit starts a round told what changed.
+  --dry-run shows the plan and spends nothing. "testeiya pipeline-check" checks
+  the file and every gate it declares, and prints the message of each gate that
+  does not pass. It exits 1 when one does not, 2 when the file is invalid.
+  --diagram also writes <name>.diagram.md: a Mermaid chart of the stages, the
+  files they pass on, and the gates, coloured by the check.
+
 Testomat.io
 
   Set TESTOMATIO to a project API key and the agent reads and writes that
@@ -180,7 +212,7 @@ Testomat.io
   Add the project id, with --project or TESTOMATIO_PROJECT_ID, and it also gets
   the Testomat.io tools. The MCP server needs the id: a token alone does not say
   which project to talk to.`;
-export const COMMANDS = ["task", "ask", "models", "skills", "doctor", "sessions", "help"];
+export const COMMANDS = ["task", "ask", "pipeline", "pipeline-check", "models", "skills", "doctor", "sessions", "help"];
 export function parseCliArgs(argv) {
     const first = argv[0];
     if (!first)
@@ -212,6 +244,28 @@ export function parseCliArgs(argv) {
         args.prompt = text;
     if ((first === "models" || first === "skills") && text)
         args.pattern = text;
+    if ((first === "pipeline" || first === "pipeline-check") && text)
+        args.pipeline = text;
+    if (first === "pipeline-check" && !text)
+        return { error: "pipeline-check needs a pipeline name or a .yml path" };
+    if (typeof values.dir === "string")
+        args.dir = values.dir;
+    if (values["dry-run"])
+        args.dryRun = true;
+    if (values.diagram)
+        args.diagram = true;
+    if (Array.isArray(values.set)) {
+        const sets = parseSets(values.set);
+        if (typeof sets === "string")
+            return { error: sets };
+        args.sets = sets;
+    }
+    if (Array.isArray(values.gate)) {
+        const gates = parseGates(values.gate);
+        if (typeof gates === "string")
+            return { error: gates };
+        args.gates = gates;
+    }
     if (Array.isArray(values.output))
         args.outputs = values.output;
     if (values.json)
@@ -246,6 +300,8 @@ export function parseCliArgs(argv) {
         args.footer = values.footer;
     if (values["no-default-footer"])
         args.noDefaultFooter = true;
+    if (values["no-thread"])
+        args.noThread = true;
     if (args.session && (args.continueLast || args.resume || args.name || args.noSession)) {
         return { error: "--session already names and continues a session" };
     }
@@ -273,17 +329,64 @@ const RUN_OPTIONS = {
     header: { type: "string" },
     footer: { type: "string" },
     "no-default-footer": { type: "boolean" },
+    "no-thread": { type: "boolean" },
+    help: HELP_FLAG,
+};
+const PIPELINE_OPTIONS = {
+    output: RUN_OPTIONS.output,
+    json: JSON_FLAG,
+    model: { type: "string" },
+    project: { type: "string" },
+    thread: { type: "string" },
+    "exit-zero": { type: "boolean" },
+    header: { type: "string" },
+    footer: { type: "string" },
+    "no-default-footer": { type: "boolean" },
+    dir: { type: "string" },
+    "dry-run": { type: "boolean" },
+    set: { type: "string", multiple: true },
+    gate: { type: "string", multiple: true },
     help: HELP_FLAG,
 };
 const OPTIONS = {
     task: RUN_OPTIONS,
     ask: RUN_OPTIONS,
+    pipeline: PIPELINE_OPTIONS,
+    "pipeline-check": {
+        json: JSON_FLAG,
+        model: { type: "string" },
+        dir: PIPELINE_OPTIONS.dir,
+        set: PIPELINE_OPTIONS.set,
+        gate: PIPELINE_OPTIONS.gate,
+        diagram: { type: "boolean" },
+        help: HELP_FLAG,
+    },
     models: { json: JSON_FLAG, help: HELP_FLAG },
     skills: { json: JSON_FLAG, help: HELP_FLAG },
     doctor: { json: JSON_FLAG, probe: { type: "boolean" }, model: { type: "string" }, help: HELP_FLAG },
     sessions: { json: JSON_FLAG, help: HELP_FLAG },
     help: {},
 };
+function parseSets(values) {
+    const sets = {};
+    for (const value of values) {
+        const equals = value.indexOf("=");
+        if (equals <= 0)
+            return `--set takes KEY=VALUE, got "${value}"`;
+        sets[value.slice(0, equals)] = value.slice(equals + 1);
+    }
+    return sets;
+}
+function parseGates(values) {
+    const gates = {};
+    for (const value of values) {
+        const colon = value.indexOf(":");
+        if (colon <= 0 || !value.slice(colon + 1).trim())
+            return `--gate takes NAME:COMMAND, got "${value}"`;
+        gates[value.slice(0, colon)] = value.slice(colon + 1);
+    }
+    return gates;
+}
 function isCommand(value) {
     return COMMANDS.includes(value);
 }