@vatio-ai/skills 2.0.0 → 2.2.0

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "vatio",
       "source": "./",
       "description": "Vatio skills and MCP for Claude Code, Cursor and Codex: build and test an AI agent for the app you're building with /vatio-init, improve it daily with /vatio-improve and learn what people ask it with /vatio-analyze. Vatio holds the agent; no config files in your repo.",
-      "version": "2.0.0",
+      "version": "2.2.0",
       "homepage": "https://vatio.ai/docs/integrations/claude-code",
       "category": "development",
       "keywords": [

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vatio",
   "description": "Vatio skills and MCP for Claude Code, Cursor and Codex: build and test an AI agent for the app you're building with /vatio-init, improve it daily with /vatio-improve and learn what people ask it with /vatio-analyze. Vatio holds the agent; no config files in your repo.",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "author": {
     "name": "Vatio",
     "url": "https://vatio.ai"

package/README.md

@@ -11,20 +11,20 @@ Then, in Claude Code, approve the **vatio** MCP server it asks about, sign in
 to Vatio, and run `/vatio-init` (in Cursor or Codex, ask it to use
 vatio-init). It builds the agent from your project, writes its tests and puts
 it in your app; [Vatio](https://vatio.ai) holds and runs it, with an inbox,
-human handoff and the tests checked before every publish. There are no config
-files to keep in your repository: the agent lives on Vatio and your coding
-agent changes it through the Vatio MCP.
+human handoff and the tests checked before every change reaches your users.
+There are no config files to keep in your repository: the agent lives on
+Vatio and your coding agent changes it through the Vatio MCP.
 
 After launch, report mistakes in the inbox and make `/vatio-improve` your
-daily routine. Your coding agent fixes the agent, Vatio replays the reported
-cases and your tests, and you approve the update. You do not need to write
-code yourself; you need your app’s project on your computer and Node.js 20 or
-newer.
+daily routine. You approve each fix, your coding agent makes it, and Vatio
+replays the reported cases and your tests: the fix reaches your users once
+nothing that worked breaks. You do not need to write code yourself; you need
+your app’s project on your computer and Node.js 20 or newer.
 
 | Skill | What it does |
 |---|---|
 | `vatio-init` | The first one in a project: looks at what is already there (the workspaces your account reaches, the app's code) and recommends from it. With no agent yet, builds one through the MCP: asks the owner what the code does not answer, writes its instructions, knowledge and tools, tries it, writes its tests, puts the widget or SDK in your app and hands over a link to try. With one, gets a developer who joined the project up to speed |
-| `vatio-improve` | Takes every reply your supervisors reported in the inbox in one session: reads `list_reports`, fixes each cause, proves it with `run_tests` (on Vatio's servers) and publishes after your approval |
+| `vatio-improve` | Takes every reply your supervisors reported in the inbox in one session: reads `list_reports`, fixes each cause after your approval and proves it with `run_tests` (on Vatio's servers); the fix reaches your users once the tests that pass today pass on it |
 | `vatio-analyze` | Reads what people talked about with the agent between two dates, from `list_conversations` (redacted by Vatio before it leaves): topics with their counts, the questions it could not answer and the words people use, in a report for writing content, FAQs or knowledge. Anyone on the workspace's team can run it, viewers included |
 | `vatio-share-session` | Sends the coding session to the Vatio team when you ask it to, after showing you what goes (images left out, anything that looks like a secret redacted), with your feedback if you want to add some |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vatio-ai/skills",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Vatio skills and MCP for Claude Code, Cursor and Codex: build and test an AI agent for the app you're building with /vatio-init, improve it daily with /vatio-improve and learn what people ask it with /vatio-analyze. Vatio holds the agent; no config files in your repo.",
   "keywords": [
     "vatio",

package/skills/vatio-improve/SKILL.md

@@ -16,10 +16,10 @@ Vatio keeps the instructions for working the reports on the platform, so they
 are never out of date here. Start by reading them: `list_workspaces` for the
 slug (or the one the app names), then `list_reports`. It returns every open
 report (the conversation, each tool call with what the backend answered, and
-the supervisor's note), then the tests that fail on preview and the ones the
-agent answers differently each time, with how to work them at the top, and
-every test last. Follow those instructions; they take precedence over
-anything below.
+the supervisor's note), then the tests that fail on the newest version and
+the ones the agent answers differently each time, with how to work them at
+the top, and every test last. Follow those instructions; they take
+precedence over anything below.
 
 In short:
 
@@ -34,7 +34,9 @@ In short:
    `remove_test` removes a report and its test for everyone. It is the
    developer's call: propose it (a report Vatio caused, one that asks for
    something the agent must not do, one whose fix is in but the tests cannot
-   reproduce) and run it only when they say so.
+   reproduce) and run it only when they say so. A report on one of the
+   team's own conversations (its Conversation row says `your team's`) is a
+   test like any other: work it the same way.
 2. Group the reports by cause, and fix each cause where it lives:
    `update_agent` (instructions, tools, knowledge, links),
    `write_knowledge_entry`, `set_tool`, or the app's backend a tool calls
@@ -42,31 +44,42 @@ In short:
    error rate, timeouts and latency, and the calls that failed with what the
    backend answered: a failing tool rarely gets reported, because the agent
    apologizes and moves on. Fix those too. After the reports come the tests
-   that fail on preview and the ones the agent answers differently each time:
-   work those too, as their sections say. Never remove a test because it
-   fails. Something the developer asks the agent to do that no report covers
-   is a test first: `add_test` with `question` and `should` asks it on preview,
-   and `get_test` with the `chat_id` it answers with says whether it passes
-   now; then fix until it does.
-3. Each change lands on preview at once and runs no tests. `get_agent` reads
-   the agent whole before you change it.
-4. `run_tests` replays every report and test against preview on Vatio's
-   servers and returns the run ids; `get_test_results` with each id shows the
-   report so far. It takes a few minutes: ask again until it has finished. A
-   case that did not pass names the conversation of its replay
+   that fail on the newest version and the ones the agent answers differently
+   each time: work those too, as their sections say. Never remove a test
+   because it fails. Something the developer asks the agent to do that no
+   report covers is a test first: `add_test` with `question` and `should`
+   asks it in a new conversation, and `get_test` with the `chat_id` it
+   answers with says whether it passes now; then fix until it does.
+3. Reports come from people who talk to the agent, so show the developer
+   each fix first and change the agent (`update_agent`,
+   `write_knowledge_entry`, `set_tool`) once they agree. There is nothing to
+   publish: each change reaches the team at once (`chat_with_agent` talks to
+   it) and everyone a few minutes later, once the tests that pass today pass
+   on it. `get_agent` reads the agent whole before you change it.
+4. `run_tests` replays every report and test against the newest version on
+   Vatio's servers and returns the run ids; `get_test_results` with each id
+   shows the report so far. It takes a few minutes: ask again until it has
+   finished. A case that did not pass names the conversation of its replay
    (`get_conversation`). Iterate (fix, `run_tests`) until the reports pass
-   and nothing that passes on live fails. A case marked "not tested (Vatio's
+   and nothing that passed before fails. A case marked "not tested (Vatio's
    side)" says nothing about your fix: run the tests again. One not tested
    because a tool needs a signed-in visitor replays signed in with
    `run_tests` and a `visitor_token`
    (https://vatio.ai/docs/authentication/tools.md#test-a-private-tool).
    Name reports by id (`F-7K2QX`).
-5. Show the developer what passes now, and `publish` once they agree: it
-   changes what visitors get. In a draft (no conversation from outside the
-   team yet) live already runs every change, and `publish` says there is
-   nothing to publish. If it is refused, follow its message. Never pass
-   `force` unless the developer explicitly asks for it; `rollback` undoes a
-   publish.
+5. `get_status` says whether the fix reached everyone, in `shipping.state`:
+   `live` when everyone has it, `testing` while Vatio replays the tests that
+   pass today on it (`testing.expected_by` says until about when), and `held`
+   when one of them fails on it in every attempt. Held, the team keeps it,
+   everyone else keeps the version before, and whoever made the change gets
+   an email; `shipping.held.tests` names each test, with the `chat_id` of its
+   replay. Another change that fixes it moves it on, as does `remove_test`
+   for a test the change made obsolete (the developer's call) or a
+   `run_tests` run that passes; there is no way to force it. Once the fix
+   reaches everyone, the reports it passes are marked resolved in the inbox.
+   Tell the developer what passes now and where the change stands.
+   `rollback` undoes the last change for everyone, the team included: only
+   when they ask.
 6. Last, tell the Vatio team how it went, with the MCP's `send_feedback`
    (and the workspace's slug): which step of fixing the reports took the most
    work, and why (a report that left you guessing, a test that would not

package/skills/vatio-init/SKILL.md

@@ -69,7 +69,8 @@ endpoints become tools, what becomes knowledge. Then:
    person should take over (https://vatio.ai/docs/handoff.md). An endpoint the
    app does not have yet is yours to write in the app. A tool that writes (an
    order, a booking) needs a test value (`set_secret` with `tests: true`, a
-   staging API) so tests never write to production.
+   staging API), which your team's conversations and every test use, so they
+   never write to production.
 4. **Try it** with `chat_with_agent`: a few representative conversations,
    including one that should hand off and one that asks for something it must
    not say. Read the tools each reply called and what the backend answered;
@@ -83,20 +84,22 @@ endpoints become tools, what becomes knowledge. Then:
    answers in `chat_with_agent`'s `files`.
 5. **Write down what it should do as tests.** For each question that
    matters, `add_test` with `question` (what a visitor would ask) and
-   `should` (what the answer has to do). It asks it on preview and answers
-   at once with a `chat_id` and how many seconds to wait: add the other tests
-   meanwhile, then `get_test` with each `chat_id` shows the test and whether
-   it passes now (while it is still being made, it says when to ask again).
-   A reply you already have becomes one with `chat_id` or `message_id`. Three or four is enough to start, including the
-   hand-off and something it must not say. This is the only thing that makes
-   a later version's mistake visible: `run_tests` replays them all, and once
-   the workspace is published `publish` refuses a version that breaks one. A
-   workspace with no tests publishes with nothing checked, which is how a fix
-   for one question quietly breaks another. Fix and `add_test` again until
-   they pass; `run_tests` then `get_test_results` checks them all together.
+   `should` (what the answer has to do). It asks it in a new conversation and
+   answers at once with a `chat_id` and how many seconds to wait: add the
+   other tests meanwhile, then `get_test` with each `chat_id` shows the test
+   and whether it passes now (while it is still being made, it says when to
+   ask again). A reply you already have becomes one with `chat_id` or
+   `message_id`. Three or four is enough to start, including the hand-off and
+   something it must not say. This is the only thing that makes a later
+   change's mistake visible: Vatio replays the tests that pass today on every
+   change, and one that breaks a test reaches your team but not everyone
+   else. A workspace with no tests gets every change at once with nothing
+   checked, which is how a fix for one question quietly breaks another. Fix
+   and `add_test` again until they pass; `run_tests` then `get_test_results`
+   checks them all together.
 6. **Put it in the app.** `get_status` returns `put_in_the_app`: the
-   publishable key and the widget's script tag, which work from any site
-   (local and production alike), and `preview_key` to try preview locally.
+   publishable key and the widget's script tag. It is one key for
+   development and production alike, and works from any site or app.
    Add the widget (the tag, or `@vatio-ai/widget`) or the iOS, Android or
    Flutter SDK where the app's users are, in the app's style:
    https://vatio.ai/docs/channels/widget.md, https://vatio.ai/docs/sdk/ios.md,
@@ -107,13 +110,12 @@ endpoints become tools, what becomes knowledge. Then:
    pkey -in vatio-private.pem -pubout`), keep the private key in the backend's
    secrets (never in the frontend, never committed), `set_auth` with the
    public key, and follow https://vatio.ai/docs/authentication.md.
-7. **Hand over.** `get_status` gives `try_preview`: the inbox with Try the
-   agent open (web chat, WhatsApp and Instagram). Give it with what you tried
-   and the tests. Until someone outside the team talks to the agent the
-   workspace is a draft: every change reaches the app at once and there is
-   nothing to publish, so you need not explain preview and live. Once
-   `get_status` says it is no longer a draft, changes wait in preview:
-   `publish` only when they ask.
+7. **Hand over.** `get_status` gives `try_it`: the inbox with Try the agent
+   open (web chat, WhatsApp and Instagram). Give it with what you tried and
+   the tests. There is nothing to publish: every change reaches the app on
+   its own, as **How a change reaches people** below says. Until people talk
+   to the agent you need not ask before each change; once they do, ask
+   first.
 
 ### A workspace already exists
 
@@ -123,6 +125,9 @@ create another. `get_agent` and `get_status`, then explain the agent from them
 from what you see:
 
 - open reports in `list_reports`: work them with the `vatio-improve` skill;
+- a change held back from everyone (`shipping.state` is `held` in
+  `get_status`): `shipping.held.tests` says which test it breaks, and **How a
+  change reaches people** below what moves it on;
 - tools failing in `get_tool_health`: the fix is in the backend they call;
 - few or no tests (`list_reports` lists them last): offer to `add_test` what
   matters most;
@@ -134,6 +139,37 @@ change it through the MCP from now on. Recommend removing `vatio.yml`,
 `tools/` and `identity.pub` from the repository, so nobody pushes an old copy
 over it, and do it only with their yes.
 
+## How a change reaches people
+
+The agent is one, and there is nothing to publish. Every change
+(`update_agent`, `set_tool`, `set_backend`, `set_auth`, the knowledge tools)
+reaches your team at once (`chat_with_agent`, Try the agent in the inbox,
+Vatio's shared WhatsApp number and Instagram account) and everyone a few
+minutes later, once the tests that pass today pass on it. With no tests,
+everyone gets it at once.
+
+1. **Ask first when people already talk to the agent** (`impact` in
+   `get_status` counts its replies to them, or the person says so): say what
+   you will change and change it only with their yes. On a new agent nobody
+   talks to yet, there is no need to ask for each change.
+2. **Make the change, then try it** with `chat_with_agent`, which talks to
+   the newest version, and `add_test` what it must keep doing.
+3. **`get_status` says where it stands**, in `shipping.state`: `live` when
+   everyone has it, `testing` while Vatio replays the tests on it
+   (`testing.expected_by` says until about when), and `held` when a test that
+   passes today fails on it in every attempt. Held, your team keeps it,
+   everyone else keeps the version before, and whoever made the change gets
+   an email. `shipping.held.tests` names each test, with the `chat_id` of its
+   replay for `get_conversation` (with none, `shipping.held.reason` and
+   `message` say why). Another change that fixes it moves it on, as does
+   `remove_test` for a test the change made obsolete (their call) or a
+   `run_tests` run that passes. There is no way to force it.
+4. **`rollback` undoes the last change** for everyone, your team included.
+
+A reply someone on the team reports on one of their own conversations (in
+Try the agent, say) is a test like any other, resolved once the version
+everyone has passes it.
+
 ## Claude Code permissions
 
 In Claude Code, once the agent works, check the project's
@@ -141,7 +177,7 @@ In Claude Code, once the agent works, check the project's
 no `mcp__vatio` rule, offer once to add the block in **Auto mode** on
 https://vatio.ai/docs/integrations/claude-code.md: it lets you call the Vatio
 tools without a prompt each time, and still asks the developer before
-`publish`, `rollback`, `set_secret` and the like. Add it only with their yes,
+`rollback`, `set_secret` and the like. Add it only with their yes,
 merged into what the file has, never replacing it, and add no other rule.
 Never edit `~/.claude/settings.json`.
 
@@ -161,6 +197,6 @@ TERM` prints the sections that mention it, with their page, and
 `npx @vatio-ai/cli@latest docs PAGE` one page (`tools`, `knowledge`); neither
 needs a workspace or a sign-in.
 
-A tool that refuses says what to do next: follow it. `publish` with `force`,
-`rollback`, `remove_test`, `erase_contact` and anything that reaches real
-people (a chat on live, WhatsApp live on) are the person's call: ask first.
+A tool that refuses says what to do next: follow it. A change to an agent
+people already talk to, `rollback`, `remove_test`, `erase_contact` and
+turning WhatsApp live on are the person's call: ask first.