release v0.0.4

Author: Remote release bot

.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
       "name": "remote-cli",
       "source": "./plugins/remote-cli",
       "description": "Tools and skills for interacting with the Remote.com partner API from the command line.",
-      "version": "v0.0.3"
+      "version": "v0.0.4"
     }
   ]
 }

README.md

@@ -56,6 +56,6 @@ After installing, the `remote-cli` skill is available in Claude Code and knows h
 
 ## Version
 
-Current release: **v0.0.3**
+Current release: **v0.0.4**
 
 See the [Releases page](https://github.com/remoteoss/remote-cli/releases) for history.

plugins/remote-cli/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "remote-cli",
-  "version": "v0.0.3",
+  "version": "v0.0.4",
   "description": "Skill that drives the `remotecli` binary against the Remote.com partner API.",
   "author": {
     "name": "Remote"

plugins/remote-cli/skills/remote-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: remote-cli
-description: Use when the user asks you to perform any Remote.com HR action — create or list time off, manage expenses (approve/decline/download receipts), list or create employments, download payslips, submit terminations — via the remotecli CLI tool in this project. Also triggers when asked to look up leave balance, employment status, or company info through the CLI.
+description: Use when the user asks you to perform any Remote.com HR action — create or list time off, manage expenses (approve/decline/download receipts), list or create employments, view or amend employment contracts (salary changes, title changes, etc.), download payslips, submit terminations — via the remotecli CLI tool in this project. Also triggers when asked to look up leave balance, employment status, or company info through the CLI.
 ---
 
 # Using the Remote CLI
@@ -22,9 +22,65 @@ remotecli companies list   # see what's saved
 remotecli use              # interactively pick the active one
 ```
 
-## Non-Interactive Usage
+## Driving the CLI Autonomously
 
-Every command that normally prompts can be driven entirely with flags — always prefer flags when acting autonomously. See `references/commands.md` for every flag per command.
+When acting without a human at the keyboard, every interactive prompt is friction — the TUI blocks waiting for keystrokes and your agent has no way to answer. Use this priority order; **top is always cheaper than bottom**:
+
+### 1. Suppress the prompt with flags (preferred)
+
+Every interactive picker has a flag equivalent. Resolve IDs via `list` filters, then pass them to the action. This requires zero special protocol and zero per-prompt round-trips.
+
+```bash
+# ❌ Picker fires — TUI blocks; the agent has no way to answer
+remotecli contracts list
+
+# ✅ Resolve the ID via a filter, then pass it
+remotecli employments list --email alice@example.com --pretty
+remotecli contracts list --employment-id emp_abc123
+```
+
+Same pattern for `expenses approve --expense-id`, `time-off approve --timeoff-id`, `payslips download --id`, `contract-amendments create --employment-id`, etc. See `references/commands.md` for the full flag inventory.
+
+### 2. Use `--json-prompts` only when a prompt is unavoidable
+
+Schema-driven flows (`employments create`, `contract-amendments create`) prompt for required fields the API doesn't expose as flags. For those, `--json-prompts` swaps the TUI for an NDJSON stdio protocol: stdout emits `{"type":"prompt", ...}` events, stdin takes one `{"answer": ...}` line per event, in order.
+
+**Read the protocol first.** The complete spec lives in `CLAUDE.md` → "JSON prompter mode" (about 30 lines). It enumerates every event type and answer shape. Don't speculate at the format — read it once and you'll know exactly what to send.
+
+Drive the whole flow in **one Bash call**, pre-computing every answer:
+
+```bash
+# After reading the schema (or doing a dry-run to learn the prompt order):
+printf '%s\n' \
+  '{"answer":"Alice Cooper"}' \
+  '{"answer":"alice@example.com"}' \
+  '{"answer":"2026-06-01"}' \
+  | remotecli --json-prompts employments create --country GBR
+```
+
+Splitting the flow across multiple Bash tool calls multiplies permission prompts and breaks the pipe. One process, one pipeline, one permission.
+
+**Discovering prompts: each probe should reveal many prompts, not one.** The prompter validates answers in order and emits the next prompt *before* reading its answer, so one Bash call with N valid answers reveals N+1 prompts. Pipe several plausible answers per probe call — `0` validates as a select or number, `"2026-06-01"` as a date, a sufficiently long string as `role_description` — and read every prompt the call emits before composing the next one. Two or three probe calls is usually enough to map a whole form; firing ten one-answer-at-a-time calls is the anti-pattern, because it costs permission prompts and round-trips for no information you couldn't have learned in a single pass. Stop probing the moment field names appear that match data you already have (`job_title`, `work_hours_per_week`, `annual_gross_salary` are all in `contracts list` output) and switch to a real run with the real values.
+
+### 3. Never write a Python wrapper
+
+If `printf | remotecli` can't express the flow, the answer is to read the schema and pre-compute the answers — **not** to wrap the CLI in `subprocess.Popen`. A wrapper script costs:
+
+- File-write permission to create the script
+- Python execution permission to run it
+- A near-guaranteed stdin-buffering bug (forgetting `flush=True`, line-buffering on pipes)
+- More permission prompts every time you iterate on the script
+
+The CLI was designed for Unix pipes. If you're reaching for Python, you've misread the protocol — go back to step 2 and re-read the `JSON prompter mode` section.
+
+### Red flags — stop and reconsider
+
+| You're about to... | Instead, do this |
+|---|---|
+| Open an interactive picker via `--json-prompts` and try to answer it | Run the matching `list` command with a filter flag, pass the resulting ID via `--<resource>-id` |
+| `cat answers.txt \| remotecli --json-prompts ...` after writing the file in a separate step | Inline the answers with `printf` in a single Bash call — no temp file, no extra permission prompt |
+| `python wrapper.py` that calls `subprocess.Popen(["remotecli", ...])` | Stop. Read `CLAUDE.md` → "JSON prompter mode". Use `printf \| remotecli` instead |
+| Run multiple Bash tool calls to drive one CLI invocation | One Bash call, one pipeline — the CLI process should not span tool invocations |
 
 ## Quick Command Reference
 
@@ -38,6 +94,10 @@ Every command that normally prompts can be driven entirely with flags — always
 | `employments list` | List employments | `--status`, `--email`, `--all` |
 | `employments create` | Onboard a new employee | `--country` |
 | `employments show <id>` | Get a single employment | — |
+| `contracts list` | List contracts for an employment for historical contracts set the only-active to false | `--employment-id`, `--only-active=false` |
+| `contract-amendments list` | List submitted contract amendments | `--employment-id`, `--status`, `--all` |
+| `contract-amendments show <id>` | Show a single amendment | — |
+| `contract-amendments create` | Submit a contract amendment | `--employment-id`, `--contract-id`, `--country` |
 | `expenses list` | List expenses | `--all`, `--pretty` |
 | `expenses create` | Submit an expense | `--employment-id`, `--amount`, `--currency`, `--expense-date`, `--title`, `--tax-amount` |
 | `expenses approve` | Approve a pending expense | `--expense-id` |
@@ -90,6 +150,25 @@ remotecli payslips download --id <id> --out-file ./payslip.pdf
 remotecli time-off balance --employment-id emp_abc123 --pretty
 ```
 
+**Amend an employee's contract (salary, title, hours, etc.):**
+
+A contract amendment is a *delta* over the current contract — never submit one without first reading the existing terms, or you'll propose changes that conflict with current state or are no-ops. When you only have a name or email, resolve the employment via `employments list` filters (not the interactive picker — filters are faster and unambiguous for autonomous use).
+
+```bash
+# 1. Resolve the employment by email/status filter (skip the picker)
+remotecli employments list --email alice@example.com --pretty
+
+# 2. Read the current active contract for context (current salary, title, work hours, etc.)
+remotecli contracts list --employment-id emp_abc123 --pretty
+
+# 3. Submit the amendment — schema-driven, country-specific, ends with a confirm step
+remotecli contract-amendments create --employment-id emp_abc123
+```
+
+**Most amendment fields are unchanged — copy them verbatim from the active contract.** Read the JSON form of `contracts list --employment-id X` (the default; don't pass `--pretty`) and take the first element of `data.employment_contracts`. For a salary raise, only `annual_gross_salary` (and `reason_for_change` / `effective_date`) actually change; every other answer — `job_title`, `role_description`, `work_hours_per_week`, `contract_duration_type`, `work_schedule`, `compensation_currency_code` — must equal the active contract's value, or the API records each one as an additional proposed change. Units already line up: `annual_gross_salary: 7200000` in `contracts list` means £72,000 in pence (minor units), and the form expects the same integer — don't divide by 100, don't convert to a decimal string, and don't reinvent `role_description` from scratch.
+
+`contract-amendments create` pulls the country and `active_contract_id` off the employment automatically; override either with `--country` / `--contract-id` if needed. After submission, track the amendment with `contract-amendments list --employment-id emp_abc123` or `contract-amendments show <amendment_id>`.
+
 ## Output Control
 
 ```bash

plugins/remote-cli/skills/remote-cli/references/commands.md

@@ -124,6 +124,76 @@ Get a single employment by ID.
 
 ---
 
+## `contracts`
+
+### `contracts list`
+
+List contracts (compensation snapshots) for a single employment. Use this to inspect the current and historical contract terms before submitting a contract amendment.
+
+```bash
+./remote contracts list [flags]
+```
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--company-token` | string | Override active company token |
+| `--employment-id` | string | Employment to list contracts for (picker if omitted) |
+| `--only-active` | bool | Return only the active or last active contract (default `true`; pass `--only-active=false` to list all) |
+| `--columns` | string | Comma-separated column names for table output |
+
+Table columns: ID, Status, Country, Job Title, Effective.
+
+---
+
+## `contract-amendments`
+
+### `contract-amendments list`
+
+List contract amendments for the active company.
+
+```bash
+./remote contract-amendments list [flags]
+```
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--company-token` | string | Override active company token |
+| `--employment-id` | string | Filter by employment ID |
+| `--status` | string | Filter by status: `submitted`, `in_review`, `done`, `canceled`, `deleted` |
+| `--columns` | string | Comma-separated column names for table output |
+| `--all` | bool | Fetch all pages |
+| `--page` | int | Page number (default: 1) |
+| `--page-size` | int | Results per page (default: 100) |
+
+Table columns: ID, Employment, Status, Reason, Effective, Submitted.
+
+### `contract-amendments show <id>`
+
+Show a single contract amendment by ID.
+
+```bash
+./remote contract-amendments show amend_abc123 [--company-token <token>]
+```
+
+### `contract-amendments create`
+
+Submit a contract amendment for an employment. **Always run `contracts list --employment-id <id>` first** to read the current terms — the amendment is a delta over the active contract, and the schema-driven form references current-state fields (salary, title, work hours, etc.).
+
+```bash
+./remote contract-amendments create [flags]
+```
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--company-token` | string | Override active company token |
+| `--employment-id` | string | Employment to amend (picker if omitted; prefer resolving via `employments list --email` for autonomous use) |
+| `--contract-id` | string | Override the employment's `active_contract_id` (rarely needed) |
+| `--country` | string | Override the employment's country (3-letter ISO; rarely needed — pulled from the employment automatically) |
+
+The flow fetches the country-specific amendment JSON Schema, prompts for each field (with the current contract's values as defaults where the schema supports it), then shows a recap and a confirm prompt before submission. On confirm, the CLI POSTs to `/v1/contract-amendments` and returns the new `amendment_id` and `status`.
+
+---
+
 ## `expenses`
 
 ### `expenses list`