ghl-workflow-fast-forward
Fast-forward contacts parked at a GoHighLevel / HighLevel workflow WAIT step to the next step — the builder's "Action statistics → move to next step" control, driven via the internal API. Use to accelerate end-to-end workflow testing (drive a multi-day wait ladder to completion in minutes instead of waiting real time), to unstick contacts stranded at a wait, or when the user says "fast-forward this wait", "skip the wait", "move parked/stuck contacts to the next step", "requeue stuck contacts", "test this long delay without waiting days", or gives an app.gohighlevel.com workflow URL and asks to push contacts past a wait. This MUTATES live enrollments (it fires whatever steps come next, i.e. real SMS/email to real people) — it is a WRITE skill and follows the plugin's write-rails. It is the mutating counterpart to the read-only get-ghl-workflow-logs.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 12
- Forks
- 5
01 前言 Front Matter
- name
- ghl-workflow-fast-forward
- description
- Fast-forward contacts parked at a GoHighLevel / HighLevel workflow WAIT step to the next step — the builder's "Action statistics → move to next step" control, driven via the internal API. Use to accelerate end-to-end workflow testing (drive a multi-day wait ladder to completion in minutes instead of waiting real time), to unstick contacts stranded at a wait, or when the user says "fast-forward this wait", "skip the wait", "move parked/stuck contacts to the next step", "requeue stuck contacts", "test this long delay without waiting days", or gives an app.gohighlevel.com workflow URL and asks to push contacts past a wait. This MUTATES live enrollments (it fires whatever steps come next, i.e. real SMS/email to real people) — it is a WRITE skill and follows the plugin's write-rails. It is the mutating counterpart to the read-only get-ghl-workflow-logs.
02 资源文件 5
- 脚本engine/ff.mjs3.4 KB
- 脚本engine/ff.test.mjs4.9 KB
- 参考文档references/fast-forward-runbook.md4.1 KB
- 脚本scripts/ff.mjs5.3 KB
- 脚本scripts/ff.test.mjs1.5 KB
03 SKILL.md 正文
Fast-forward a GHL workflow wait
MCP routing: If the
uxie-ghl-internal-mcpserver is registered in this session, prefer itsfast_forward_contactstool over running this skill's scripts directly — the tool wraps this same engine behind a confirmation gate and preview. Fall back to this skill's own scripts when the server is not registered.
The builder can move a contact sitting at a wait step straight to the next step — the UI path
is: click the wait step → its contact-count badge → Action statistics → tick the contacts →
the running-person icon → Move all. That control posts to an internal endpoint, so it can be
driven programmatically. This turns a 120-hour chase ladder into a ~3-minute test: loop
count-per-step → move past each wait → read the logs → repeat. It is the single biggest
constraint removed from GHL end-to-end testing.
This is a WRITE skill. Moving a contact fires whatever comes after the wait — real SMS,
real email, real pipeline moves — to real people. Treat it like publishing, not like reading
logs. It is the mutating sibling of get-ghl-workflow-logs (which is read-only and explicitly
must NOT do this).
What it does — and does not — do
- It moves a contact to the NEXT step. It does not evaluate the wait's own window/condition (the "only on weekdays 9–5" gate, the appointment-anchor, the reply-wait). You are skipping the wait, not simulating its passage of time — anything the wait was supposed to check is bypassed.
- It is per-contact / selective: you pass exactly the workflow-status ids you want moved. It is not inherently all-or-nothing.
statusIdsare workflow-status ULIDs, not contactIds — you read them fromdetails-by-step. Passing a contactId where a statusId is expected moves nothing (or the wrong thing).
Gates — pass these before the first move
This skill issues internal-API writes, so both write-rails gates apply, plus a third gate specific to fast-forwarding (it sends real comms):
- Gate 1 — Owned-account check (
${CLAUDE_PLUGIN_ROOT}/docs/write-rails.md§Gate 1). Every session, before the first move: confirm the authenticated user is an admin on the targetlocationId. Refuse otherwise; override only via the logged, in-their-own-words path. - Gate 2 — ToS disclosure (
write-rails.md§Gate 2). Once per workspace: this goes through the undocumented internal API. Record acknowledgment at.ghl/tos-acknowledged. - Gate 3 — Real-comms confirmation (this skill). Fast-forwarding is meant for e2e
testing with synthetic contacts on a workflow you own. Before moving:
- Prefer synthetic test contacts you created for the test, on a scratch/owned workflow.
- If the contacts to be moved are or might be real leads on a live client workflow, STOP and get explicit confirmation naming what will be moved and what it will fire. Do not blanket-move. A wrong move here sends a real, un-recallable message to a real customer.
- Never move
--allat a step without an explicit, per-run--confirmfrom the user.
Auth (header format, JWT capture, token claims, expiry) lives ONLY in
${CLAUDE_PLUGIN_ROOT}/docs/auth-jwt-capture.md. The intercepted JWT must be scoped to the
workflow-builder iframe origin or the endpoints 401.
Default workflow
- Parse the target. Need
locationId+workflowId(from the URL…/workflow/{WORKFLOW_ID}). Ask if missing. - Gates. Run Gate 1 + (first-time) Gate 2; hold Gate 3 in mind for the move itself.
- Capture the scoped JWT per the canonical auth doc. Point
GHL_INTERNAL_TOK_FILEat the file that holds the capturedAuthorization: Bearer …header. - See where everyone is (read-only).
count-per-steplists every occupied step + counts;details-by-steplists the parked enrollments at one step (with their status ULIDs). The script'speekdoes this without writing. - Move — selectively. Move by contactId (one test contact) or by explicit statusIds. Only
use
--all --confirmwhen you genuinely want every parked contact at that step moved, and the account/workflow is yours to test on. - Verify with logs. Re-read via
get-ghl-workflow-logs(orcount-per-step) — the moved contact should now be at the step after the wait and the intervening step(s) should show inlogs/v2. Loop back to step 4 for the next wait in the ladder.
The script
${CLAUDE_PLUGIN_ROOT}/skills/ghl-workflow-fast-forward/scripts/ff.mjs — an importable module
- CLI. It defaults to read-only; a move requires an explicit subcommand and, for
--all, an explicit--confirm.
GHL_INTERNAL_TOK_FILE=/path/to/token.txt node ff.mjs <LOC> <WID> peek # count-per-step
GHL_INTERNAL_TOK_FILE=… node ff.mjs <LOC> <WID> peek <STEP_ID> # details-by-step (who's parked)
GHL_INTERNAL_TOK_FILE=… node ff.mjs <LOC> <WID> move <STEP_ID> --contact <CID> # move ONE contact past the wait
GHL_INTERNAL_TOK_FILE=… node ff.mjs <LOC> <WID> move <STEP_ID> --status <ID,ID> # move explicit status ULIDs
GHL_INTERNAL_TOK_FILE=… node ff.mjs <LOC> <WID> move <STEP_ID> --all --confirm # move EVERY parked contact (paginates)
Without --confirm, a --all move prints what WOULD move and stops (dry run). move with an
explicit --contact/--status performs the move.
Live-proven (GROM AU, 2026-07-18)
Drove a 3-contact / 2-wait canary end to end via this skill's ff.mjs, tags proving each step
actually fired (not just a pointer move):
count-per-step/details-by-step/requeue-stuck-statusesall work with the iframe JWT.details-by-step_ids are workflow-status ULIDs, distinct fromcontactId.- Selective move with >1 parked ✅ — 3 parked at a wait, moved ONLY one (by contactId); it alone advanced (its next step fired) and the other two stayed put.
- Bulk
--all✅ — moved the remaining two; both advanced. The--alldry-run guard (no--confirm) correctly moved nothing and reportedwouldMove. - Pagination ✅ —
allParkedwithpageSize=1drained all 3 rows across pages. - Full ladder driven to
end_of_workflowin ~2 min (both waits fast-forwarded).
Still not proven — flag, don't assert
- The UI "Select all N contacts" link may post a different body (a flag rather than an id
list). The script deliberately builds the id list itself (
allParked→requeue) rather than relying on that link, so this is untested and doesn't matter for the script — but if you ever reverse-engineer that link, capture its body separately.
Resources
references/fast-forward-runbook.md— exact endpoints, headers, request/response shapes, pagination, and the selective-vs-bulk decision.scripts/ff.mjs— the driver (peek + selective/bulk move).${CLAUDE_PLUGIN_ROOT}/docs/write-rails.md— the two mandatory write gates.${CLAUDE_PLUGIN_ROOT}/docs/auth-jwt-capture.md— canonical JWT capture + header format.
04 同仓库更多 Skills
ghl-workflow-specialist
Senior GoHighLevel workflow architect — designs automations (nurture, speed-to-lead, no-show recovery, internal ops, data hygiene, routing) grounded in the full trigger/action catalog and known anti-patterns, and reviews or fixes live workflows. Use when the user asks what automation to set up for X, wants a workflow designed, or asks why a live workflow is not getting through, is failing, or whether an A/B test is done. Recons + reads the client brief before proposing anything. Once approved, the build itself goes to create-ghl-workflow.
ghl-voice-ai
Build and configure GoHighLevel Voice AI phone agents — the prompt, the voice, the actions (appointment booking, call/agent transfer, contact-field extraction, SMS, workflows, custom API), knowledge bases, MCP servers, working hours, and outbound consent. Use when the user says 'set up a voice agent', 'build a phone agent', 'my AI should answer calls', 'book appointments over the phone', 'outbound calling', 'the agent isn't transferring calls', 'change the voice', or names a Voice AI agent. Internal API — the public rail exposes only how the agent sounds, not what it does.
ghl-system-conventions
House conventions for building GoHighLevel systems — workflow naming and structure, tag/field/custom-value discipline, pipeline and opportunity decisions, copy rules, and the pre-build approval document the operator signs off before anything gets created. Account-agnostic, for ANY GHL sub-account. Use whenever designing, building, editing, reviewing, or discussing GHL workflows, automations, pipelines, stages, opportunities, tags, custom fields, custom values, calendars, or AI agents — even if the user never says "conventions" or "standards". Load it BEFORE proposing a design or creating any GHL object, so the proposal already looks the way the operator wants it.
ghl-snapshots
GoHighLevel snapshots — capturing a sub-account's assets into a reusable snapshot, refreshing one, curating what it carries, and checking load conflicts. Use when a task involves creating or updating a snapshot, deciding what an account template should include, asking why a snapshot came out empty or is stuck processing, or planning a rollout onto other sub-accounts. Read it BEFORE calling any /snapshots path by raw_request — two of the write endpoints silently do the wrong thing.
ghl-reverse-engineering
Map a GoHighLevel internal surface exhaustively — enumerate every screen, panel, control and save path a feature has, capture the real request behind each one, prove what each field does by differential, and write the result into the corpus. Use when the user wants to understand how a GHL feature works under the hood, extend an engine to an object the public API can't reach, re-sweep a surface that already has partial coverage, or asks to reverse-engineer / sniff / capture / trace anything internal. GHL permits inspecting your own account's traffic. This is a MAPPING skill, not a lookup: it finishes when the surface is exhausted, not when the first endpoint is found.
ghl-recheck
Re-prove the plugin's tools live on the designated sandbox, record a proof run per tool the suites exercised, and record failures in the backlog. Use when the operator invokes /ghl-recheck or asks to re-check, re-prove or refresh proofs. Records only — never fixes.