feat(gravity-flow-abilities): add Gravity Flow abilities skill and refine Gravity Forms skill

.gitignore

@@ -5,3 +5,4 @@
 .DS_Store
 .env
 dist/
+.claude/settings.local.json

change_log.txt

@@ -1,3 +1,12 @@
+### 1.1.0 | 2026-08-04
+- gravity-flow-abilities: Add the skill — workflow guidance for Gravity Flow abilities via the WordPress Abilities API (MCP), covering step CRUD, approval policies, reassignment, and feasibility consultation.
+- gravity-forms-abilities: Add a phone pitfall row and a phone step to the form-creation workflow; an omitted phoneFormat breaks rendering on older Gravity Forms versions.
+- gravity-forms-abilities: Add documentation for the notification and confirmation write abilities.
+- gravity-forms-abilities: Correct the shared MCP endpoint path (/wp-json/mcp/mcp-adapter-default-server) and the meta-tool names (mcp-adapter-discover-abilities, mcp-adapter-execute-ability, mcp-adapter-get-ability-info).
+- gravity-forms-abilities: Document the Gravity Forms 3.0 international phone field value shape.
+- gravity-forms-abilities: Fix the entries-search escape-hatch examples to use form_ids.
+- gravity-forms-abilities: Require an explicit phoneFormat on phone fields — document all three valid values plus defaultCountry/showCountryCode, and surface the format_options discovery key from system-field-types.
+
 ### 1.0.2 | 2026-06-18
 - gravity-forms-abilities: Add a warning against deprecated Ready Classes in favor of the layout grid.
 - gravity-forms-abilities: Add documentation for the 100-entry bulk-delete cap and the count/delete loop.

skills/gravity-flow-abilities/references/feasibility.md

@@ -0,0 +1,62 @@
+# Feasibility Facts (for "can Gravity Flow do X?" consultations)
+
+Customers often ask whether a workflow design is possible before building. These are verified product facts — confirm, then point at the relevant abilities or admin screens. Never invent capabilities; anything not listed here should be verified against docs.gravityflow.io before claiming it.
+
+## Core workflow capabilities
+
+- **Approval chains**: unlimited sequential approval steps; per-step assignees (users, roles, emails, field-resolved); `"all"` (unanimous) or `"any"` approval policy per step; conditions on any step (GF conditional logic on field values) enable branch-per-department/amount/type designs.
+- **Approval loops / send-back**: approval steps can **revert** to a user-input step (revise-and-resubmit loops) and reject-destinations can point at any earlier step — multi-round review loops are native.
+- **User input steps**: assignees edit a configured subset of fields (`editable_fields`), can save progress (`in_progress`) before completing; display-fields config controls what each step's assignees see (reviewer-privacy patterns).
+- **Consent capture**: use the native Gravity Forms **Consent field** (a required GDPR checkbox with descriptive text) — not a plain checkbox. Signature capture needs the Signature add-on.
+- **Two-actor patterns** (candidate submits, referent completes hidden fields): initial submission + a user_input step whose editable fields are the referent-only fields. Field-level conditional logic on steps requires the step's "field conditional logic" setting.
+- **External participants without WordPress accounts**: email assignees act via signed token links from notification emails — supported for approval and user input steps. They cannot use MCP.
+- **Scheduling/delays**: steps can be scheduled (delay after previous step, or date/date-field based). Expiration with destinations handles "no response by X" routing; resend settings handle reminders.
+- **Notifications**: per-step assignee notifications plus approval/rejection/complete notifications, all templatable with merge tags; `{workflow_entry_link}` is the assignee's action link — REQUIRED for email assignees to act.
+
+## Integrations (verify the add-on is installed before promising)
+
+- **Payment-then-review** (e.g. paid application → manual approval): two verified patterns — payment at submission via a GF payment add-on feed, or a mid-workflow `stripe_checkout` step (Flow Stripe extension) where the assignee pays through Stripe-hosted Checkout from their workflow detail page. Payment itself always happens on Stripe's hosted page — never through MCP; agents triage/diagnose payment steps and verify outcomes (payment_status, transaction id, timeline "Processed" event). Capture/refund/cancel steps automate post-payment actions.
+- **Role change / user registration on approval**: GF User Registration add-on feeds run as workflow steps — approve → the registration/role-update feed step fires. Rejection routes around it.
+- **Signatures**: the GF Signature add-on's field works inside workflows; approval steps can display and collect signature fields (signature on approval requires the field on the form and step display/editable config).
+- **PDF generation**: Gravity Flow PDF add-on generates PDFs from entries with merge tags (including signatures) as a workflow step.
+- **Feed add-on steps**: most GF feed add-ons (webhooks, email marketing, sheets connectors…) can run as workflow steps, i.e. "after approval, push to X".
+- **Form-to-form**: Form Connector add-on creates/updates entries in other forms as steps (intake → per-team forms patterns).
+
+## Documentation links (verified)
+
+Cite the SPECIFIC article for each capability you mention — a feasibility answer without deep links is incomplete. Verified URLs:
+
+**Gravity Flow — steps**
+- Approval step: https://docs.gravityflow.io/approval-step-type/
+- User Input step: https://docs.gravityflow.io/user-input-step-type/
+- Notification step: https://docs.gravityflow.io/notification-step-type/
+- Choice Routing step: https://docs.gravityflow.io/choice-routing-step/
+- Outgoing Webhook step: https://docs.gravityflow.io/outgoing-webhook-step-type/
+- Update User step: https://docs.gravityflow.io/update-user-step/
+- Types of steps and where they come from: https://docs.gravityflow.io/types-of-steps-and-where-they-come-from/
+- Step condition: https://docs.gravityflow.io/condition/
+- Next Step / routing: https://docs.gravityflow.io/next-step/
+- Schedule / delay: https://docs.gravityflow.io/schedule/
+
+**Gravity Flow — categories** (deep-link within when the topic isn't listed above)
+- Flow fundamentals: https://docs.gravityflow.io/category/flow-fundamentals/
+- Extensions (PDF, Form Connector, Stripe…): https://docs.gravityflow.io/category/extensions/
+- Developer reference: https://docs.gravityflow.io/category/developers/
+
+**Gravity Forms — fields & logic**
+- Consent field (GDPR checkbox): https://docs.gravityforms.com/consent/
+- Signature field (needs the Signature add-on): https://docs.gravityforms.com/signature/
+- Enabling conditional logic for fields: https://docs.gravityforms.com/enable-conditional-logic/
+- Conditional logic for notifications: https://docs.gravityforms.com/enable-conditional-logic-for-notifications/
+- Conditional logic for feeds: https://docs.gravityforms.com/enabling-conditional-logic-for-feeds/
+- Merge tags: https://docs.gravityforms.com/category/user-guides/merge-tags-getting-started/
+
+## Scope expectations
+
+For large multi-workflow asks (e.g. "eight country-specific incorporation workflows"), set expectations: design one workflow as the template, validate it end-to-end, then replicate per variant — and ask the narrowing questions first (which steps differ per country/region? who acts at each step? what does 'done' mean?). Do not attempt to build the entire estate in one pass.
+
+## Currently NOT possible via abilities
+
+- Creating WordPress pages/posts (inbox blocks, dashboards) — hand off to the human with exact instructions.
+- Creating/modifying step types outside the allowlist (approval, user_input, notification) — feed-addon and routing steps are configured in the Flow admin UI.
+- Acting as an email assignee (no credential exists) — only delegated processing by a workflow admin.

skills/gravity-flow-abilities/references/processing.md

@@ -0,0 +1,70 @@
+# steps-process — Complete Guide
+
+`gravityflow/steps-process` performs an assignee action on an entry's **current** step. It cannot target an arbitrary step — the workflow's position decides what is processable.
+
+## Inputs
+
+| Input | Notes |
+|---|---|
+| `entry_id` | Required |
+| `status` | Required — see per-type table below |
+| `note` | Optional in general; REQUIRED when the step config demands one for the status (common on reject/revert), and ALWAYS required for delegated calls. Include one anyway — approvals without context make poor audit trail |
+| `field_values` | user_input steps only; `input_{field_id}` / `input_{field_id}.{sub}` keys |
+| `assignee_key` | Delegation (`type|id`); requires workflow-admin permission + `note` |
+
+## Valid status by step type
+
+| Step type | Statuses | Notes |
+|---|---|---|
+| `approval` | `approved`, `rejected`, `revert` | `revert` only when the step has reverting enabled — it sends the entry back to a designated user-input step without recording a rejection |
+| `user_input` | `complete`, `in_progress` | `in_progress` saves `field_values` without completing the step |
+| anything else | — | `operation_not_supported`. Notification/webhook/feed steps complete autonomously; if one is stuck, use `steps-restart` / `workflow-send-to-step` |
+
+`system-step-types` reports a `processable` flag per type — check it when unsure.
+
+## Authorization
+
+- **As self:** authenticated user must be a *pending* assignee on the current step (directly, via role, or via a field that resolved to them). Same rule as the web inbox.
+- **Delegated (`assignee_key`):** requires workflow-admin permission. The key must resolve to a *pending* assignee on the current step. `note` is required. The result is dual-attributed:
+  - Timeline note: attributed to the acting admin, body prefixed `[On behalf of {display_name} ({key})]`
+  - Activity feed: a `delegated` assignee event (acting admin in `display_name`, acted-for assignee in `assignee_key`) alongside the normal status event
+
+## field_values and editable fields
+
+User-input steps declare which fields assignees may edit. `field_values` is validated fail-closed:
+
+- Keys must match `input_{field_id}` or `input_{field_id}.{sub}` / `input_{field_id}_{sub}` for compound fields
+- Every referenced field must be in the step's editable list — otherwise the call fails with an error naming the editable field IDs, and nothing is saved
+- Approval steps accept no `field_values` at all
+
+To know the editable fields in advance: `steps-get` on the current step. Value formats follow Gravity Forms conventions (see the gravity-forms-abilities skill's field-config reference).
+
+## Response shape
+
+```json
+{
+  "success": true,
+  "step_status": "approved",
+  "feedback": "Entry Approved",
+  "final_status": "pending",
+  "current_step_id": 42
+}
+```
+
+- `step_status` — the status you requested, confirmed
+- `feedback` — human-readable pipeline message
+- `final_status` + `current_step_id` — where the workflow stands NOW (the workflow may have advanced several steps: notifications/webhooks between interactive steps complete inline). `current_step_id: null` with a terminal `final_status` means the workflow finished
+
+After processing, trust this response over assumptions — reject destinations and conditional branches mean the "next" step is not always the next in order.
+
+## Errors
+
+| Error | Meaning | Agent response |
+|---|---|---|
+| `operation_not_supported` | Current step type is not processable | Use the unstick ladder (steps-restart / send-to-step), not repeated processing |
+| `assignee_already_processed` | This assignee already acted on this step | Done — do not retry; check `workflow-status-get` for current state |
+| `gravityflow_ability_validation_failed` | Names each concrete failure (e.g. "note: A note is required") | Retry the same call with the missing/corrected values |
+| `gravityflow_ability_field_not_editable` | `field_values` touched a non-editable field; error names the editable IDs | Resend with only listed fields; report the rest to the user |
+| `gravityflow_ability_not_pending_assignee` | You are not a pending assignee on the current step | Check `workflow-status-get` assignees; do not escalate on your own |
+| `gravityflow_ability_delegation_denied` / `gravityflow_ability_note_required` | Delegation needs workflow-admin permission and a reason note | Add the note; if permission is missing, hand back to the user |
+| Entry not found | Entry nonexistent OR not visible to this user | Indistinguishable by design — verify via `status-search`, don't enumerate |

skills/gravity-flow-abilities/references/status-reference.md

@@ -0,0 +1,92 @@
+# Status Vocabulary, Assignee Keys, and Meta-Key Escape Hatch
+
+## Workflow final status (`final_status`)
+
+| Value | Meaning |
+|---|---|
+| `pending` | Workflow in flight — a current step exists |
+| `cancelled` | Workflow cancelled — assignees purged, entry retained |
+| `complete` | Finished; final step was a non-decision step (e.g. user input) |
+| `approved` | Finished; final step was an approval that was approved |
+| `rejected` | Finished; final step was an approval that was rejected |
+
+Key fact (verified against live behavior): on completion, Flow records the **final step's status** as the workflow status. Agents must treat `approved`, `rejected`, and `complete` all as terminal. `current_step` is `null` for any terminal status and also before the workflow starts.
+
+A rejected approval does not necessarily end the workflow — reject destinations can route to earlier steps or alternate branches. Read `workflow-status-get` after acting rather than assuming.
+
+## Step statuses
+
+| Value | Meaning |
+|---|---|
+| `queued` | Step not reached yet |
+| `pending` | Step active, waiting on assignees |
+| `complete` | Step finished (user input completed, notification sent, feed processed…) |
+| `approved` / `rejected` | Approval step outcome |
+| `revert` | Approval reverted to a user-input step for changes |
+| `cancelled` | Step was skipped (workflow-send-to-step) or the workflow was cancelled while it was active |
+
+## Per-assignee statuses
+
+Within a pending step, each assignee has their own status (`pending`, `approved`, `rejected`, `complete`). Multi-assignee approval steps combine them by policy — `workflow-status-get`'s `current_step.approval_policy` states it directly: `"all"` (unanimous — every assignee must act; one approval with the step still pending is normal, name who is still pending) or `"any"` (first decision wins). The live list is `assignees[] { key, display_name, status }`.
+
+This policy is a **configurable step setting**, not a fixed law. If a workflow is stuck because it demands unanimous approval and the user wants any-one-approves instead (or vice versa), that is a `steps-update` on the step's approval settings — surface it as the real remedy (or a decision point to confirm), rather than only restarting/re-notifying to chase the missing approvals.
+
+## Assignee key format
+
+`type|id`:
+
+| Key | Resolves to |
+|---|---|
+| `user_id|5` | WordPress user ID 5 |
+| `role|approver` | Every user with the role |
+| `email|pat@example.com` | An email address (may have no WP account) |
+
+Step *configurations* may also use field-resolved types (`assignee_field`, `assignee_user_field`, `email_field`) that resolve per entry at runtime — which is why `steps-get` shows configured assignees but only `workflow-status-get` shows an entry's actual ones.
+
+**Email assignees** act through signed token links embedded in notification emails. They never authenticate to WordPress, so no MCP credential corresponds to them. An agent cannot act *as* an email assignee — only a workflow admin can act *on behalf of* one via delegated `steps-process` with `assignee_key: "email|..."`.
+
+**"Their link doesn't work" playbook** — always cover all three parts: (1) explain the model — email assignees act via the signed link in their notification, not by logging in, and links are entry+step+assignee-specific and can expire or be superseded; (2) verify with `workflow-status-get` that the step is still pending and they are still a listed assignee (if the step moved on, the old link is dead by design); (3) remediate with `steps-restart` (admin) to re-send a fresh token link — or delegated `steps-process` if the admin should act for them. Also check the step's notification message actually contains `{workflow_entry_link}` (use `{workflow_entry_link:page_id=N}` to point the link at a specific front-end inbox page).
+
+## Workflow entry meta keys (escape hatch)
+
+When `status-search` filters aren't expressive enough, these meta keys work as `field_filters` keys in `gravityforms/entries-search`:
+
+| Key | Value |
+|---|---|
+| `workflow_final_status` | Final status (table above) |
+| `workflow_step` | Current step ID (integer) |
+| `workflow_step_status_{step_id}` | That step's status for the entry |
+| `workflow_user_id_{user_id}` | Per-assignee status when user {id} is/was an assignee |
+| `workflow_role_{role}` | Per-assignee status for a role assignee |
+| `workflow_email_{email}` | Per-assignee status for an email assignee |
+| `workflow_timestamp` | Unix timestamp the current step started |
+
+Example — all entries stuck on step 41 in form 3:
+
+```json
+{
+  "form_ids": [3],
+  "search_criteria": {
+    "field_filters": [
+      { "key": "workflow_step", "value": "41" }
+    ]
+  }
+}
+```
+
+Note: GF's `entries-search` takes `form_ids` (an array), not `form_id`.
+
+Example — everything user 7 has ever approved on form 3:
+
+```json
+{
+  "form_ids": [3],
+  "search_criteria": {
+    "field_filters": [
+      { "key": "workflow_user_id_7", "value": "approved" }
+    ]
+  }
+}
+```
+
+Prefer `status-search` when its filters suffice — it applies workflow-aware shaping and permission scoping. The escape hatch is subject to GF's entry permissions, not Flow's entry-visibility predicate.