@pipefy/pipefy-process-coder 0.1.0 → 0.1.2

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

@@ -1,91 +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.
+---
+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.