gtm-workflow

GTM workflow

Trigger

Apply this Lifecycle SOP to a saved GTM workflow from creation through updates, runs, inspection, deployment, and deletion.

Scope

Own workflow code, result tables, migrations, dry runs, runs, diagrams, and deployment metadata inside the root workflows/ project. gtm-workspace, gtm-icp, and gtm-persona own their respective artifacts.

Contract

Field	Public contract
Reads	The request, accepted workspace context, supplied rows, workflow files, and environment-held credentials
Writes	Workflow code, result tables, migrations, schedules, and deployment metadata
Outputs	A verified saved workflow, run result, inspection, diagram, deployment, or deletion
Approval	One plain-language card covers creation, save, hosted deployment, one-row test, and small fixes; later runs and checkpoints each get one card
Persists	Prepared local commits and approved pushes, plus workflow rows and cost records
Handoff	Workspace, ICP, and persona lifecycle changes go to their owning skills

Inputs

Use the request, resolved organization context, relevant accepted ICP and persona files, supplied rows, current workflow project, environment-held credentials, and accepted cost limits.

Roles

The agent authors and verifies the work. The user approves one card covering saved changes, hosted deployment, the one-row test, stated external effects, and stated test cost; later full runs and user-chosen checkpoints each receive one approval.

Procedure

1. Resolve the GTM workspace and requested lifecycle action. Ask one unnumbered question only when a result-changing fact cannot be inferred.
2. For create, copy templates/ from this installed skill into the workspace's root workflows/ project when absent, rename gitignore and vercelignore with leading dots, copy .env.example to .env, and write GTM_HOST=<claude|codex> for the host you run in. Workflow files live at workflows/workflows/<slug>.ts. Read the library, SDK choices, and the interaction standard. Read deployment only for deploy work and local use only for open/local work.
3. Draft workflow code, its table, a one-row input, and the author-written Diagram: header. A schedule request also writes the matching vercel.json cron entry. Run npm run db:generate, npm run gtm -- verify <slug> --input data/test-1-row.json, git add <changed workflow, table, and migration paths>, and git commit -qm "<plain summary>" silently. data/ is ignored on purpose: the test input stays local and the card names it. Use git commit --amend after feedback when the prior commit was not pushed; after a push, a fix is a new commit.
4. Post one plan card stating what it does, reads, saves, where it runs, one-row test cost, possible data removal, and any missing key. Its last line is Saving and testing. Back in a few minutes. Invoke the matching command with that card as its approval summary: hosted, git push && npm run gtm -- run <slug> --url https://<production-host> --input data/test-1-row.json --wait-live --background, which returns at once and starts the test in the background after the deploy is live; local, npm run gtm -- run <slug> --input data/test-1-row.json, which starts the local server itself when needed.
5. After approval, collect hosted results with watch_url on /api/runs/latest?workflow=<slug>&head=<pushed commit> until a run appears, then on /api/runs/<runKey> until it finishes; at a keyboard use npm run gtm -- runs get <id> --wait 600. A failed run carries its plain reason in error; show it. Fix small failures and retry the identical approved step up to twice. Present a fresh card when cost, external effects, saved tables, command, or summary changes.
6. On success say Built and tested. Ready to run whenever you want. and provide the picture plus Diagram, Runs, and Data links. A later full run gets one short card and one real run command. Cancel asks What would you like me to change?; revise from free text and re-ask at the same step.
7. For update, inspect, or delete, preserve the same one-card boundary: verify and commit silently, then request approval for the first effectful command. Name deletion and data-removing SQL on the card. Use expand-then-contract for renames while a run may be waiting.