Skip to content
AssureSwarm Docs

Agent Operating Guide

/coach-form-create

Author a form schema on a workflow step, fields, types, and required flags, submitted as a suggestion the assignee then fills.

Add a form schema to a workflow step so its assignee can enter structured data on the step’s form page. The skill gathers the field definitions, key, label, type, required flag, and any options, validates them, and submits one suggestion via suggest_change. Because this changes the step’s schema, the preview lands in the step viewer’s schema-diff, not on the form page. To put values into an existing form, use /coach-form-fill.

When to use

Section titled “When to use”

When you want to create, add, build, or design a form for a workflow step. For filling an existing form with values rather than defining its fields, use /coach-form-fill instead.

Inputs

Section titled “Inputs”
Flag Required Notes
--step-id <id> If not clear from context The step to add the form to. Inferred from the current view if absent.
--fields <json> No A pre-built array of field definitions. If present, interactive gathering is skipped and the schema is just validated.
--replace No If the step already has a form, replace it without the confirmation prompt. Loses any submitted values.

Example

Section titled “Example”

/coach-form-create --step-id <id> first checks the step for an existing form (offering to replace it or switch to filling if one’s there), then walks you through fields one at a time, say a control_effective radio with yes/no options, a test_notes textarea, and an evidence file field, validates the keys, and submits an update suggestion. You approve it in the step’s schema-diff view, and the form goes live at the step’s form page.

Good to know

Section titled “Good to know”
  • It’s a schema-change suggestion. The preview lands in the step viewer’s schema-diff UI, the right place to review a schema change, not on the form page. After approval the form is live at the step’s form route.
  • Field keys are stable identifiers. Later /coach-form-fill calls reference them by key, so renaming one means resubmitting. Keys are lowercase, kebab- or snake-case.
  • Field types are a fixed set: text, textarea, number, date, select, checkbox, radio, email, url, file. select and radio need options; checkbox is a single yes/no; file takes an accept allowlist and a maxFiles cap.
  • File fields hold document ids. At fill time /coach-form-fill uploads the file via upload_document first, then stores [documentId] in the field.
  • One form per step. If the step already has one, the skill refuses and offers to replace it (losing submitted values) or switch to filling. Archived steps lock the schema and the write fails.
Section titled “Related”