---
name: revly
description: Use whenever the Revly MCP tools (revly_*) are connected and you finish a piece of work, are asked to save progress, wrap up, or prepare a release, or are about to start new work in a Revly-tracked project. Keeps the snapshot timeline readable by renaming auto-captured snapshots in the background, creates a release-candidate checkpoint at real milestones, keeps its own throwaway test/debug files out of Revly's history (and so out of production) via .gitignore, and tells the developer how to deploy to production (and the database, if needed) themselves.
---

# Revly upkeep for AI agents

Revly watches the project folder and auto-captures snapshots with generic,
timestamp-style messages. This skill keeps the history meaningful and gets
finished work ready for the developer to release. It only uses existing
`revly_*` tools. If they aren't connected, run the setup in the MCP server's
instructions (`revly_project`, then `revly_connect`) before anything else.

## Hard limits (never cross these)

- **Never deploy.** There is no tool for it, by design. Deployment (files over
  SFTP/FTP/FTPS, and database schema changes) is always started by the
  developer in the Revly desktop app.
- **Never create a release.** `revly_create_release` only works on a checkpoint
  the developer has already reviewed and resolved. Don't call it to "move
  things along", and don't try to get around a refusal.
- **Never ignore (or untrack) files you didn't create for scratch use** - and never ignore
  anything the developer deploys. When unsure whether a file ships, ask.
- **Never invent test results.** Pass `tests_passed`/`tests_failed` only from
  tests you actually ran.

## 1. Before starting work

Call `revly_list_checkpoints`. Titles and descriptions are the project's
memory - use them to avoid repeating or contradicting earlier work.

## 2. After each coherent piece of work: rename snapshots in the background

Most of your edits become snapshots you never created, with a generic message.
Once a feature, fix, or refactor step is finished:

1. If your environment supports subagents, hand this to one so it doesn't
   interrupt the main task; otherwise do it inline right after finishing.
2. `revly_list_snapshots`, pick the snapshots produced by the work you just
   did, and call `revly_rename_snapshot` on each with a specific message: what
   changed and why, written like a commit message (not a file list).
3. Don't ask the developer first - it only rewrites the label, never content.
4. Skip any snapshot you're about to fold into a checkpoint (step 4).

**Name limit:** snapshot messages and checkpoint titles are capped (default 72
characters, set by the developer in Settings > Snapshot Naming; read it as
`name_character_limit` from `revly_get_settings`). Write names to fit - the short
"what" in the name, the "why" in the checkpoint description. Longer text is refused.
Never raise the limit yourself; only `revly_set_name_limit` if the developer asks.

## 3. Keep your throwaway files out of Revly (and out of production)

While testing and fixing you create files that must never ship: repro scripts, debug
dumps, scratch fixtures, test output, screenshots, logs, `*.bak` copies. Agents often forget
to delete them, and Revly's watcher snapshots every new file within a couple of seconds -
so unless you act first, they end up in the history, the Changes list, checkpoints, and
eventually a release and a deploy. Revly (snapshots, checkpoints, releases, deployments) only
ever works from tracked files, so a file git ignores can't reach production.

**Set up once, at the start of the work** (read `.gitignore` first - it already exists and
already ignores `.revly/`, `node_modules/`, `vendor/`, `tmp/`, `logs/`, `cache/`, `uploads/`,
`storage/`; only append what's missing, one pattern per line, never reorder or remove lines):
- Add a scratch folder entry, e.g. `.scratch/`, and **put every throwaway file inside it**
  (repro scripts, dumps, screenshots, fixtures, test output). One folder, one line, nothing
  scattered through the source tree.
- If a tool forces a throwaway file elsewhere (a test runner's output dir, a coverage folder,
  `*.log`), add that **specific** path or glob to `.gitignore` *before* you create the file
  (or the moment you do), e.g. `coverage/`, `test-results/`, `*.log`, `*.orig`, `*.bak`.

**What not to ignore** - be narrow, never `*`, `src/`, `*.js` and the like:
- source code, configuration the app needs, lockfiles, migrations, and the project's **real**
  tests (a test that belongs in the repo stays tracked - only throwaway ones are ignored);
- anything the developer deploys. If build output (`dist/`, `build/`) is part of what they
  ship, it is **not** scratch. If you can't tell, ask.

**If a scratch file was already snapshotted** (a `.gitignore` entry has no effect on a file
git already tracks - check with `git ls-files --error-unmatch <path>`): for files **you**
created, stop tracking them with `git rm --cached -r -- <path>` (the file stays on disk and
its history stays recoverable) and make sure the path is ignored. Do this only for your own
scratch files, never for anything the developer wrote.

**Then clean up.** Delete your scratch files when you're done - the ignore entry is a safety
net for the ones you forget, not permission to leave a mess. In your end-of-work message, say
which patterns you added to `.gitignore` and what you removed, so the developer can see it.

## 4. At a real milestone: create a release-candidate checkpoint yourself

A milestone is a finished feature or fix with its own coherent diff - the
kind of thing that would be one changelog line. Not every rename round is one.
Don't ask; just create it:

- `revly_create_checkpoint` with a short title and a real description (what
  changed and why - required when the project has human review on).
- Start the description with `Release candidate:` and end it with a suggested
  version and reason. Call `revly_next_release_version` first: it returns the project's
  own versioning format (the developer sets it under Releases > gear) and the suggested
  next version(s) - never invent a version in a different style. For the default semantic
  format it offers a patch, minor and major bump: use MAJOR for breaking changes, MINOR
  for new compatible functionality, PATCH for fixes only, e.g. `Suggested: 1.4.0 (minor -
  new backward-compatible feature)`. Other formats (date, counter, custom template) just
  have one suggestion.
- Report real test counts if you ran tests, via `tests_passed`/`tests_failed`/
  `tests_note`.
- If the checkpoint is created from the project root and the project has a
  connected database, call `revly_preview_schema_deploy` (read-only) to learn
  whether table structure changed. If you just changed the schema, call
  `revly_check_schema` first. Mention what you found in the notice below.

## 4b. When you change data in the project's database

If the project has a connected local database and you are about to insert, update or delete rows (by any tool),
let Revly record it so the developer can deploy it later:

1. `revly_data_watch_status` - are the tables you'll touch already watched?
2. If not, `revly_start_data_watch` for those tables **before** you make the change (it records every change exactly,
   with before/after values). A table without a primary key, or with a binary column, can't be watched.
3. If triggers can't be installed, make the change and then `revly_report_data_changes` with the SQL you ran - plain
   `INSERT INTO` / `UPDATE ... SET` / `DELETE FROM` on one table each, never for a table that is watched.
4. After the change, `revly_list_data_changes` to confirm Revly captured what you meant to do.
5. Say in your end-of-work message which tables you changed and that the developer should review and deploy them from
   **Database > Data changes**. You cannot deploy, discard or restore data changes.

## 4c. Config files

If the developer has set a config file (for example `.env`), Revly keeps it git-ignored from then on (earlier snapshots,
and the backups and shared contributions that carry that history, may still contain its real values) and maintains a
credential-free `{filename}.example` beside it. Never commit the real config or paste its values into snapshot messages or
checkpoint titles/descriptions. Call `revly_config_status` (read-only, never returns contents) before sharing or
backing up work to check it is set up, in step and ignored. If you add a setting the project needs, tell the developer
so they can add it to their real config; never put real credentials in the `.example`. Setting the config file is a
human step (project page > Set config in the desktop app) - you have no tool for it.

## 4d. Backups

`revly_create_backup` writes an encrypted `.revbak` file to the project's configured backup folder. It never includes a
database, and it fails with a clear message until the developer has set up backup protection (a recovery phrase) in the
Revly app's Backups page - when that happens, tell the developer to set it up; you cannot. You cannot make collaborator
backups, share backups with teammates, approve key requests, touch backup keys, recovery phrases or recovery kits, or
restore a backup. You also cannot redeem Collaborator Codes, run restore scripts or write config values. Those are
human steps in the desktop app.

## 5. Always tell the developer how to ship it

After creating a checkpoint (and whenever they ask "how do I deploy?"), end
your message with this short notice, adapted to what you found:

> **Ready for you to release.** I created checkpoint "<title>" (suggested
> version <x.y.z>). Nothing is deployed - that stays with you:
> 1. In Revly, open the project's **Checkpoints** page, review and resolve it.
> 2. Create the release from it (I can draft it, named by this project's
>    versioning format, once it's resolved, if you want).
> 3. **Production:** open **Deployments**, choose the release and a profile
>    (staging first if you have one), and start the deploy.
> 4. **Database** *(only if needed - <say whether table structure changed>)*:
>    open **Database**, preview the plan (destructive statements are flagged
>    and need your explicit acknowledgement), then deploy it.
>
> Ask me for this guide any time.

Leave step 4 out entirely if there's no database connection or no structural
change. If you couldn't tell, say so rather than guessing.

## 6. Before ending a session

First, make sure your own scratch files are deleted or ignored (step 3).

Call `revly_status`. If `pending_changes` is above zero, those changes are not
yet captured: create a snapshot or, if it's a milestone, a checkpoint as above.