@pipefy/pipefy-process-coder 0.1.0

package/.agents/skills/ppc-pipefy-pipe-authoring/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: ppc-pipefy-pipe-authoring
+description: Use when writing or editing the JSON of a Pipefy pipe's structure in a pipefy-process-coder workspace — phases, fields, automations, field conditions, labels, webhooks, pipe relations, preferences, public form. Covers the file layout, referencing entities that do not exist yet, and the specific edits that fail silently because a mutation accepts them and ignores them.
+---
+
+# Authoring pipe structure JSON
+
+Read `ppc-pipefy-workspace` first for the loop and the identity rules. This is the
+detail: what goes in which file, and which edits look fine and are not.
+
+## Where things live
+
+```
+pipes/<id>--<name>/
+  pipe.json                    the repo row: name, noun, public, title_field_id
+  phases/NN--name.json         the phase, its fields[], jump_target_ids[], team_member_ids[]
+  automations/<name>.json      the automation, its condition, field_maps, response_schemas
+  field-conditions/<name>.json the condition and its actions
+  labels.json  webhooks.json  public-form.json  preferences.json  relations.json
+  _readonly/  _non-snapshot/  _meta.json
+```
+
+**Fields live inside their phase file.** That is where they make sense and where
+you will edit them most. Ordering comes from the `index` value inside the file,
+never from the filename — renumbering works without renaming.
+
+The start form is a real phase at `index: 0`. Deleting or reindexing it is
+catastrophic; the validator refuses.
+
+## Creating something new
+
+```json
+{ "id": null, "_new": true, "uuid": "<fresh v4>", "label": "Severity", "type_id": "select", … }
+```
+
+A new field nested in an existing phase file needs no `phase_id` — it inherits its
+owner's. A field in a *new* phase leaves it null; the compiler substitutes the
+phase's real id after the phase is created.
+
+**Referencing something you are creating in the same edit:** leave
+`%{_new:<its uuid>}` and the applier substitutes the real id once it exists. This
+works in automation `field_maps`, condition `field_address`, `jump_target_ids`,
+and field-condition action targets.
+
+## What cannot be changed at all
+
+| Edit | Why |
+| --- | --- |
+| a field's `type_id` | `updatePhaseField` has no `type_id`. Delete+create destroys every existing value. |
+| a field's `phase_id` | same — no input, and moving it would destroy the data |
+| a phase's `index` | `createPhase` takes an index, `updatePhase` does not |
+| a pipe's `description` | `UpdatePipeInput` has no `description` field at all |
+| `start_form_title` | no input on any preference mutation |
+| anything under `_readonly/` | no public write path exists |
+
+If a request needs one of these, say so and stop. `pipe plan` refuses them per
+column, with the reason.
+
+## The silent failures — every one of these cost a live incident
+
+These are edits the API *accepts* and does not apply, or applies wrongly. They are
+guarded now, but understanding them stops you writing them.
+
+**A mutation can succeed and change nothing.** Arguments are filtered against the
+live schema, so an argument the mutation has no input for is dropped and the call
+returns success. `description`, `anyone_can_create_card` and `create_card_label`
+all did this on `updatePipe`. That is why the registry names settable columns per
+entity rather than trusting the mutation.
+
+**Some arguments want a uuid where the payload stores an id.**
+`updatePipe.title_field_id` takes the field's **uuid** or slug, never the numeric
+id the payload holds. `archiveField` takes `{ uuid }`. Both are translated for you.
+
+**`phaseSettings` reports failure for changes it has already made.** Observed on
+three separate runs, with the row present in the read-back and timestamped to the
+failing call. Its errors are inconclusive — re-read before assuming nothing
+happened.
+
+**`hidden_top_buttons` and `hidden_start_form_attributes` are closed sets:**
+`Assignees, Attachments, Checklist, Comments, DueDate, Labels`. Anything else is
+rejected mid-apply. Checked offline now.
+
+**Every event and action accepts a fixed parameter list, and nothing enforces it.**
+Read `REFERENCE.md` in the workspace before writing an automation. It is generated
+by `pipe pull` from the API and lists each event's `event_params`, each action's
+`action_params`, and which pairings are refused.
+
+The reason it needs reading: the schema publishes these lists, then types
+`event_id`, `action_id` and `type_id` as `ID` and `String`, so GraphQL validates
+none of them. A wrong value returns `is invalid` or `All fields must be filled
+properly.` — naming nothing — partway through an apply. And the mistakes are
+near-misses, not nonsense:
+
+- `card_moved` takes only `to_phase_id`. `in_phase_id` is real, on
+  `card_inbox_received_email`.
+- `card_id` is accepted on `update_card_field` and refused on `move_single_card`.
+
+`pipe validate` catches all of it offline and names the parameter, so run it before
+`plan`. Treat it as the backstop, not the reference.
+
+**Automation params mix naming conventions.** `AutomationActionParamsInput` has
+`card_id`, `to_phase_id` and `field_map` in snake_case, but `taskParams`,
+`aiParams` and `httpMethod` in camelCase. Getting one wrong deleted a live
+automation once, because the update strategy is delete-then-recreate.
+
+**Pipe relation flags are spelled differently in the mutation and the payload.**
+`createPipeRelation` says `canCreateNewItems`; the payload row says
+`can_create_connected_cards`. Set both, or read the one that is there.
+
+**A phase's jump set is set-replacing.** `jump_target_ids` is written whole. Never
+append blindly to a set you have not fully read.
+
+## Cross-surface obligations
+
+**Deleting a field obliges you to fix every reference to it.** Automations and
+conditions hold bare numeric ids inside opaque JSON — `"field_address": "<fieldId>"`,
+`"trigger_field_ids": ["<fieldId>"]`, `"%{<fieldId>}"`. `pipe validate` fails on a
+dangling reference by design. `MAPPING.md` translates every id.
+
+**If the pipe has iPaaS flows, a field may be referenced there too**, by slug,
+and the tool cannot yet see it. Check `flows/` if it exists before deleting a
+field. See `ppc-pipefy-flow-authoring`.
+
+## A worked shape: creating a phase with fields and a jump
+
+The numbers below are made up — use the real ids from `MAPPING.md`.
+
+```json
+// phases/09--customer-validation.json
+{
+  "id": null, "_new": true, "uuid": "<fresh v4>",
+  "name": "Customer Validation", "index": 9, "done": false,
+  "repo_id": 100200300,
+  "fields": [
+    { "id": null, "_new": true, "uuid": "<fresh v4>", "label": "Customer acceptance",
+      "type_id": "select", "options": ["Accepted", "Needs rework", "Declined"],
+      "index": 0, "required": false, "repo_id": 100200300 }
+  ],
+  "jump_target_ids": [400500600],
+  "team_member_ids": []
+}
+```
+
+Set `index` on new phases explicitly and leave existing ones alone — their index
+cannot be edited. Creating a phase auto-links jumps, so state the jump set you
+want or the platform's default stands.

package/.agents/skills/ppc-pipefy-process-design/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: ppc-pipefy-process-design
+description: Use when deciding HOW to build a requirement in Pipefy — which mechanism a need calls for (phase, field condition, automation, iPaaS flow, pipe relation, phase jump, connector field), and how to shape a process so it survives contact with real users. Read before authoring, when the question is "what should this look like" rather than "what JSON does this need".
+---
+
+# Designing a process in Pipefy
+
+Most bad Pipefy builds are not bad JSON. They are the right JSON for the wrong
+mechanism — an automation doing what a field condition should, a `CODE` node doing
+what a piece action does, a flow built where a phase would have been enough.
+
+Pick the mechanism first.
+
+## Choosing the mechanism
+
+Work down this list and stop at the first one that fits. Each rung costs more to
+build, more to explain, and more to debug than the one above it.
+
+| Need | Mechanism | Why it is the cheapest fit |
+| --- | --- | --- |
+| Show or hide a field depending on another field | **field condition** | Instant, no run history, no failure mode. Never build this as an automation. |
+| Constrain where a card can move | **phase jump set** | Structural. The board enforces it; no rule can be out of date. |
+| Stamp a timestamp, copy a value, set a label, move a card, send a task or email — **within one pipe** | **automation** | Native, visible in the pipe, no external dependency, no separate credential |
+| Compute something from fields in the same card | **automation with a formula, or an AI action** | Still inside the pipe |
+| Link cards between two pipes so people can navigate between them | **pipe relation + connector field** | Structural and bidirectional. An automation that "creates a card" does not link anything. |
+| Hold a reusable list people pick from — departments, products, suppliers, services | **a database**, not a pipe | A database has columns and records but no workflow. Reach it with a `connector` field. Reaching for a pipe here gives you phases nobody moves cards through. |
+| Store rows that a process reads but nobody works on | **a database** | If a row has no owner and no next step, it is reference data. Cards are for work that moves. |
+| Create a card in another pipe when something happens | **automation with `create_card` and `action_repo_id`** | Cross-pipe *writes* are within the automation engine's reach |
+| **Read** a pipe other than the one that triggered | **iPaaS flow** | The automation engine cannot. This is the real dividing line. |
+| Touch anything outside Pipefy — Slack, HTTP, Sheets, an ERP | **iPaaS flow** | Only iPaaS has pieces |
+| Aggregate across many cards, or run on a schedule | **iPaaS flow** | No automation trigger does either |
+| Anything else, plus arbitrary logic | **iPaaS flow with a `CODE` node** | Last rung. See the ladder below. |
+
+### The dividing line worth memorising
+
+**An automation can write to another pipe. It cannot read one.** That single fact
+decides most automation-versus-flow questions. "When X completes, open a card in
+Y" is an automation. "When X completes, check whether the card in Y exists" is a
+flow.
+
+### Inside a flow, the same discipline applies
+
+1. A **piece action** that already does it — check the catalogue first.
+2. An **inline formula expression** in a free-text input.
+3. A **`CODE` node**, only when no piece fits and the logic exceeds a formula.
+
+A `CODE` node is where the destination of a write can be computed at runtime,
+which means no static check can see it. That is the most expensive kind of bug in
+this domain — prefer a piece.
+
+## Shaping the process itself
+
+**Name the phases after states, not actions.** "Qualification & Prioritization",
+not "Qualify". A card *is in* a state; it does not *do* a phase.
+
+**Every phase needs an exit.** A phase whose `jump_target_ids` is empty is a dead
+end — cards arrive and cannot leave. Author the jump set explicitly; creating a
+phase auto-links jumps, and the platform's default is rarely the process you meant.
+
+**Make required fields answerable at the moment they are asked.** An intake form
+that requires a value only known after triage is a form nobody can submit. Real
+example: a Customer Success intake required "Account tier" and "Customer impact",
+which meant an automated handoff from another pipe could never satisfy it — the
+form was blocked until both became triage-time fields.
+
+**Distinguish intake from work.** The start form is what the requester knows; the
+first phase is what the team adds. Do not put "Triage owner" on the start form.
+
+**Let the last phase mean something.** Set `done: true` on the phase that ends the
+process. Webhooks and `cardDone` triggers depend on it, and a pipe whose final
+phase is not marked done cannot fire either.
+
+**Give closure a reason.** A "Rejected / Closed" phase with a `select` for the
+reason turns a dead card into data. Without it, nobody can answer "why do we
+decline things".
+
+## Designing the integration, not just the flow
+
+**Silence on success, noise on failure.** A flow that messages someone every time
+things go right gets muted, and then the one that matters is invisible too. If both
+outcomes are worth saying, say different things — and make the failure louder.
+
+**Assume the other side can be missing.** A cross-pipe read returns an empty list
+when the thing you expected was never created. That empty list is usually the most
+interesting outcome — handle it in a `ROUTER` branch rather than letting the flow
+run on with nothing.
+
+**Let a search fail without stopping the flow.** Set `continueOnFailure` on the
+step that can legitimately find nothing, so the branch that reports "not found"
+is reachable.
+
+**Never assume a connection exists in another workspace.** Connections are
+pipe-scoped. A flow that works in one pipe will not import into another that has
+no connection for the same piece.
+
+## Reviewing a process someone else built
+
+Ask these in order. Each has caught a real problem.
+
+1. **Does every phase have an exit?** Check every `jump_target_ids`.
+2. **Can the start form actually be submitted** by the people and systems that
+   need to submit it?
+3. **Is any required field only knowable later?**
+4. **Does the final phase have `done: true`?**
+5. **Does anything reference a field that no longer exists?** `pipe validate`
+   answers this; a dangling reference is an error by design.
+6. **If the pipe has flows, does any of them read a field the pipe is about to
+   lose?** The tool cannot check this yet — look at `flows/` yourself.
+7. **Is any automation doing a field condition's job?** Those are the first
+   things to delete.
+8. **Are there duplicate automations?** Two identical rules on one trigger is
+   almost always the residue of a failed apply, not a decision.
+
+## Two failure modes specific to this tool
+
+**A partial apply leaves created entities looking new.** If an apply half-fails,
+the files may still say `"id": null, "_new": true` for things that now exist.
+Re-planning would create them twice. `pipe apply` repairs this automatically, and
+`pipe verify --adopt` does it on demand — but if you see a diff proposing to create
+something you know exists, that is the cause.
+
+**A clean `pipe diff` covers flows too** — but only where they were readable.
+Check `pipes/<id>--<name>/flows/_meta.json`: `coverage: "complete"` means the
+flows were compared and match. **`coverage: "unknown"` means iPaaS could not be
+reached for that pipe, so its flows were not compared at all** — and a pipe can
+diff clean while its actual behaviour changed entirely, because the change was in
+a flow nobody looked at. That is the one case where a clean diff is not proof.

package/.agents/skills/ppc-pipefy-workspace/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: ppc-pipefy-workspace
+description: Use when working in a pipefy-process-coder workspace — pulling a Pipefy pipe to disk, editing its JSON, diffing, planning and applying changes back. Covers the loop, which command to run when, what each generated doc is for, and the safety rules that make an apply trustworthy. Start here before editing anything.
+---
+
+# Working in a Pipefy workspace
+
+A workspace is a Pipefy pipe pulled to disk as JSON. You edit the files; the tool
+turns your edits into API calls. Nothing about a pipe is edited through this tool
+except by changing a file and applying it.
+
+## The loop, and why each step exists
+
+```bash
+pipe pull <pipeId> --out ./my-pipe   # the pipe AND its iPaaS flows
+cd my-pipe
+# edit the JSON
+pipe validate                     # shape + referential integrity. Offline, instant.
+pipe diff                         # what you changed — pipe structure and flows
+pipe plan --dry-run               # is every change applicable? refuses if not
+pipe apply                        # snapshot, apply step by step, verify, adopt
+```
+
+**One loop covers both halves of a process.** A pipe's iPaaS flows are entities of
+that pipe — its own webhook URLs carry their ids — so they are pulled, diffed,
+planned and applied by the same commands, and land under
+`pipes/<id>--<name>/flows/`. `--no-flows` opts out of the flow half.
+
+**`pipe validate && pipe plan --dry-run` must both be clean before you propose an
+apply.** Both are free — validate needs no network, plan sends no writes — so
+iterate against them yourself rather than asking the user to run an apply and see.
+
+`pipe apply` does four things in order: snapshots the pipe as a rollback point,
+executes step by step persisting each status so a failure is resumable, reads the
+pipe back and diffs it against your intent, then adopts the result into the files
+so server-assigned ids are real. If it half-succeeds, read the output — it tells
+you whether to `--resume` or re-plan.
+
+## Read these first, in this order
+
+Every workspace generates three docs. They are not filler.
+
+| | |
+| --- | --- |
+| `AGENTS.md` | the editing rules for *this* workspace, including what its read path could and could not see |
+| `MAPPING.md` | every field id → label, slug, type and phase. **You need this constantly**, because automations and conditions reference fields by bare numeric id |
+| `CAPABILITIES.md` | what this endpoint can actually write, and the reason for every gap |
+| `REFERENCE.md` | what the API accepts wherever a value comes from a fixed list — automation event and action parameters, field `type_id`, colours. **Read it before writing an automation**: those lists are published by the schema and enforced by nothing, so a wrong value is only ever reported as `is invalid` |
+
+`pipe capabilities` prints the same registry with reasons. When a change is
+refused, that is where the answer is.
+
+## The rules that are not style preferences
+
+- **`id` is server-owned.** Never invent one, never edit one, never reuse one.
+- **A new entity is `"id": null` plus `"_new": true`.** For phases, fields,
+  automations and labels — the only four arrays with one — also add a fresh v4
+  `uuid`. Everything else is identified by its owner.
+- **To delete, remove the object or the file.** Never a tombstone.
+- **`_`-prefixed keys are tool metadata.** Leave them alone.
+- **Never edit under `_readonly/` or `_non-snapshot/`.** No write path exists;
+  plan refuses them by path alone.
+
+## Coverage: absence is not always absence
+
+Every entity group carries `complete`, `partial` or `unknown` coverage in
+`_meta.json`. An `unknown` group means the read path could not see it — not that
+the pipe has none. Such a group is never diffed and never applied.
+
+This matters most on a reconstructed pull (no snapshots): webhooks or automations
+may be `unknown`, and adding to a list you cannot fully see risks duplicating what
+is already there. Check `_meta.json` before concluding a pipe lacks something.
+
+## Where to go next
+
+| Task | Skill |
+| --- | --- |
+| Editing phases, fields, automations, conditions, labels | `ppc-pipefy-pipe-authoring` |
+| Editing or building an iPaaS (Advanced Automations) flow | `ppc-pipefy-flow-authoring` |
+| Deciding *which* Pipefy mechanism a requirement needs | `ppc-pipefy-process-design` |
+
+## Two habits worth keeping
+
+**Diff before you explain.** `pipe diff` on a real change costs ~150 tokens and
+tells you exactly what you altered. Reading the whole pipe back to check your work
+costs 50× that and is less reliable.
+
+**Believe the refusal.** When `pipe plan` says a change has no write path, it is
+because the mutation genuinely lacks that input — the registry records the reason
+per column. Do not route around it with a delete and a create; that destroys data.
+Say so plainly and stop.