Skip to content
AssureSwarm Docs

Agent Operating Guide

/coach-item-update

Change field values on an existing item, or archive it: validated against the schema and submitted as one suggestion for a human to approve.

Change field values on a single existing item of any admin-configured type, or archive it. The skill resolves the item (by id, or by type plus a title search), shows you a current → proposed line for each field it’s about to change, validates the new values against the field definitions, and submits one suggestion for a human to approve: nothing is written to your tenant directly.

When to use

Section titled “When to use”

When you want to edit an item that already exists: reassign a risk’s owner, move an audit into fieldwork, correct a value, rename a record, or archive a retired control. To reassign a user across many items at once, or make mass data changes, use the admin Bulk Import page instead.

Inputs

Section titled “Inputs”
Flag Required Notes
--id <item-id> One of these two Identify the item directly by its id.
--type <slug> + --title <text> One of these two Resolve the item by type plus a full-text title search.
--values <json> No A JSON object of field keys to new values. Partial is fine: the rest is gathered interactively.
--archive No Archive the item instead of, or in addition to, field updates.
--reason <text> No One sentence for the suggestion’s reason, to help the approver decide.

Example

Section titled “Example”

/coach-item-update --id RISK-42 --values '{"phase": "fieldwork"}' reads the risk’s current values, shows phase: planning → fieldwork, validates fieldwork against the field’s options, and submits an update suggestion. You review and approve it in Canvas: the change doesn’t land until you do. Passing --archive instead sets the type’s archival status (or the platform’s archived flag), taking the item out of active views while keeping its record.

Good to know

Section titled “Good to know”
  • Only changed fields travel. The preview renders the diff against current values; re-sending unchanged fields adds noise to the approval and can clobber concurrent edits.
  • Archival is not deletion. It takes the item out of active views but preserves its record and full history. Deletes are a separate flow this skill never emits.
  • Archived items are locked: an update against one fails with a permission error. To grant someone view access to an archived project without unarchiving it, the skill submits a minimal viewer-only patch and logs it for the audit trail.
  • MULTISELECT updates replace the whole array. To add one value, the skill reads the current array, appends, and sends the full new set.
  • USER and RELATION fields take ids, not names: the skill resolves a name or email to an id before building the payload.
Section titled “Related”