diff --git a/CHANGELOG.md b/CHANGELOG.md index 3032e0d0c..057d058ce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Changed +- **Skill `pipefy-process-design`**: a build request defaults to `build`, so automations and AI agents in a new process start on. Authorization has four levels, with separate permission for each external effect. A rule added to a pipe from before the conversation starts off when the pipe has cards that the rule can match. A time or schedule rule in a pipe with cards also starts off. The builder reads these rules again and activates them in the same build, without another yes. An inactive request, an unconfirmed assumption, or a missing phase connection keeps the dependent rule off. A creation rejected for a missing connection stays skipped. The specification records acceptance examples and pending work. The skill recommends AI for each step that needs it, with native rules first and one part per step. Confirmation of the specification authorizes its AI recommendations. The skill returns a 14-field specification, writes nothing to Pipefy, and works without a connected organization. +- **Skill `pipefy-automations`, start state**: a new "Start state" section gives the cases in which a build creates an automation off. In all other cases, the build creates it on. `create_ai_automation` has no `active` input, so a new recipe creates an inactive AI automation in one `create_automation` call with `generate_with_ai` and `active=false`. The CLI reference has the same recipe and the activation command. The simulation section now names AI automations, the only kind that `simulate_automation` accepts. The simulation recipe removes response-only metadata from the saved rule before it sends input parameters. A `field_updated` rule limited to one phase needs a supported condition for that limit. Without one, the rule stays off and the limit stays pending. - **SDK / MCP / CLI knowledge bases**: plain text, document, and data lookup writes cap `name` at 80 characters and `description` at 300 characters. These are the limits the Pipefy UI forms enforce. The cap for `description` was 900, and `name` had no cap. An item over either cap cannot be saved from the UI until the user shortens it. A write over either cap fails with a `ValueError` before the mutation is sent, and the MCP tools and CLI commands return that message. Stored items do not change. An update that omits `name` or `description` keeps the stored value, whatever its length. ## [0.5.6-beta.1] - 2026-11-03 diff --git a/plugins/pipefy/README.md b/plugins/pipefy/README.md index b19ce192e..32249c941 100644 --- a/plugins/pipefy/README.md +++ b/plugins/pipefy/README.md @@ -28,7 +28,7 @@ Each skill folder holds a `SKILL.md` with the shared domain guidance. MCP client | **Introspection** | [pipefy-introspection](skills/pipefy-introspection/SKILL.md) | Schema discovery and GraphQL fallback. | | **Attachments** | [pipefy-attachments](skills/pipefy-attachments/SKILL.md) | Upload files to card or table-record attachment fields. | | **Building** | [pipefy-building](skills/pipefy-building/SKILL.md) | Thin router: map build/configure intent → domain skill. Not a delivery playbook. | -| **Process Design** | [pipefy-process-design](skills/pipefy-process-design/SKILL.md) | Process architecture (consulting; not execution). | +| **Process Design** | [pipefy-process-design](skills/pipefy-process-design/SKILL.md) | Design a process with the user and return a process specification that a builder can use (consulting, writes nothing). | | **Process Impact** | [pipefy-process-impact](skills/pipefy-process-impact/SKILL.md) | Where an automation or AI agent returns the most time: one hop, the arithmetic, the cheapest step (consulting; not execution). | | **Process Intelligence** | [pipefy-process-intelligence](skills/pipefy-process-intelligence/SKILL.md) | Analyze pipes for improvement opportunities. | | **API Fallback** | [pipefy-api-fallback](skills/pipefy-api-fallback/SKILL.md) | Raw GraphQL fallback when higher-level tools are insufficient. | diff --git a/plugins/pipefy/skills/pipefy-automations/SKILL.md b/plugins/pipefy/skills/pipefy-automations/SKILL.md index d6e607944..bacdbcd2e 100644 --- a/plugins/pipefy/skills/pipefy-automations/SKILL.md +++ b/plugins/pipefy/skills/pipefy-automations/SKILL.md @@ -17,6 +17,32 @@ For AI agents (conversational agents with behaviors), see `pipefy-ai-agents`. --- +## Start state + +A build request defaults to `build`. Automations for a process created in this conversation start on. +Test each part with acceptance cards before real cards arrive. +Create an automation off only in these cases: + +- The user asks for `build inactive`, in any words. +- The pipe existed before this conversation and has cards that the rule can match. +- A time rule or a scheduled rule runs in a pipe with cards. +- The rule reads a business assumption that the user did not confirm. +- A move needs a phase connection that does not exist. + +For the existing-card and time-rule cases, read the saved rule and compare it with the specification. +If no other off case applies, activate the rule in the same build. Do not ask for another yes. +Keep a rule off when the user asked for it, until the user permits activation. +Keep a rule with a pending assumption off until the user confirms that assumption. +Keep a rule with a missing connection off until that connection exists. +Activate only when none of these conditions still requires an off state. +If the tool rejects a missing connection, skip that rule until the connection exists. + +Create traditional and task automations with `active=false` for an off case. Otherwise, use `active=true`. +For an AI automation that must start off, use "Create an AI automation inactive" below. +Each webhook, email outside the company, or member invitation still needs its own yes. That yes does not change the build level. + +--- + ## Traditional automations (rules engine) | Operation | Purpose | @@ -75,6 +101,42 @@ Logs, usage, and job exports for automations live in `pipefy-observability` (`ge --- +## Create an AI automation inactive + +Use this recipe when "Start state" requires an inactive AI automation. +`create_ai_automation` has no `active` input. It creates an active rule. +Do not create an active rule and then disable it. Use one `create_automation` call with `active=false`. + +1. Read the input and output field `internal_id` values from the pipe. +2. Run `validate_ai_automation_prompt` with the prompt and output `field_ids`. + Continue only when `valid` is true. +3. Use `action_id=generate_with_ai` and `active=false` in `create_automation`. + Put the prompt in `extra_input.action_params.aiParams.value`. + Put output field ids in `fieldIds` and AI skill ids in `skillsIds`. + Use an empty `skillsIds` list when no AI skill applies. + Preserve the selected `event_params` and `condition` in `extra_input`. + Without a user condition, send the explicit default condition from the example. + +The ids below are examples. Replace them with ids from the pipe. +This example uses `card_created`, which needs no `event_params`: + +```text +create_automation pipe_id=67890 name="Summarize intake" trigger_id=card_created action_id=generate_with_ai active=false extra_input={"action_params":{"aiParams":{"value":"Summarize %{900000102} into the summary field.","fieldIds":["900000101"],"skillsIds":[]}},"condition":{"expressions":[{"structure_id":0,"field_address":"","operation":"","value":""}],"expressions_structure":[[0]]}} +``` + +4. Read the created rule with `get_ai_automation`. + Make sure that `active` is false and the prompt, fields, event, and condition match the request. +5. Test the saved prompt on acceptance cards with [Steps: simulate an AI automation](#steps-simulate-an-ai-automation). + If the output differs from the expected result, keep the rule off. +6. For a temporary off case, use `update_ai_automation` with `active=true` after the read and acceptance tests. + Keep the rule off if another off case still applies. Read the rule again after activation. + +The SDK returns the id in `createAutomation.automation.id`. +MCP clients read `automation.id` from the success response. +CLI users follow [the inactive AI recipe](references/cli.md#create-an-ai-automation-inactive). + +--- + ## Steps — create a traditional automation 1. **Discover events** for the pipe: `get_automation_events pipe_id=67890`. @@ -128,7 +190,8 @@ Use when the user wants an if/then rule to **stamp or copy values** onto the tri For `update_card_field`, `acceptedParameters` omits `field_map`; use the payload shape below (see [docs/mcp/tools/automations-and-ai.md](https://github.com/pipefy/ai-toolkit/blob/main/docs/mcp/tools/automations-and-ai.md)). Prefer `value_token` from `get_automation_event_attributes` when stamping execution time. -3. **Create disabled** (`active=false`) so the rule does not fire while you verify: +3. Use the state from "Start state". This example assumes a temporary off case. + For that case, create disabled (`active=false`): ``` create_automation pipe_id=67890 name="Stamp execution time on new cards" trigger_id=card_created action_id=update_card_field active=false extra_input={"action_params":{"card_id":"%{id}","field_map":[{"fieldId":"","inputMode":"copy_from","value":"%{automation_event_execution_datetime}"}],"fields_map_order":[""]}} @@ -152,18 +215,19 @@ Use when the user wants an if/then rule to **stamp or copy values** onto the tri --- -## Steps — simulate a traditional automation +## Steps: simulate an AI automation `simulate_automation` is **AI-only** today (only `generate_with_ai` `action_id` is accepted). For non-AI rules, watch `get_automation_logs` after the trigger fires. -1. Read a working rule first: `get_automation automation_id=` — copy `event_params` and `action_params` verbatim. -2. Simulate with a real sample card: +1. Read the saved rule with `get_automation automation_id=`. Keep its `event_id`. Use only its saved `aiParams` inside `action_params`. +2. Build `event_params` from the saved non-null values, without `phase`. For `card_created`, omit `event_params`. +3. Simulate on a sample card with those inputs. The example rule uses `card_created`: ``` - simulate_automation pipe_id=67890 action_id=generate_with_ai sample_card_id=456 + simulate_automation pipe_id=67890 action_id=generate_with_ai sample_card_id=456 event_id=card_created action_params={"aiParams":{"value":"Summarize %{900000102} into the summary field.","fieldIds":["900000101"],"skillsIds":[]}} ``` -3. Read the immediate result. It may contain `simulation_id` + `status:"processing"` with null `simulationResult`. Keep the ID and read the simulation again through `execute_graphql`; calling `simulate_automation` again starts a new simulation: +4. Read the immediate result. It can contain `simulation_id`, `status:"processing"`, and a null `simulationResult`. Keep the ID. Each `simulate_automation` call starts a new simulation. Read the existing simulation through `execute_graphql`: ```graphql query { automationSimulation(simulationId: "") { status simulationResult details { errorType message } } } @@ -200,6 +264,15 @@ The constraint is a denylist. A pair is invalid when the `event_id` appears in t Recurring rules take their schedule outside `event_params`: `scheduler_frequency` (`hourly`, `daily`, `weekly`, `monthly`) plus `schedulerCron`, which is an object of five required strings (`minute`, `hour`, `dayOfMonth`, `month`, `dayOfWeek`), not a cron string. +### Field changes and phase restrictions + +For `field_updated`, `triggerFieldIds` selects which fields changed. It does not limit the card's current phase. +`get_automation_events` lists only `trigger_field_ids` for this event. `in_phase_id` belongs to `card_inbox_received_email`, not `field_updated`. +If the specification limits the current phase, preserve that restriction with a separate supported condition. +Do not omit that restriction or invent an event parameter, condition field, or operation. +If no supported condition preserves the restriction, create the rule off and report the requirement as pending or manual. +Do not activate the rule or report it ready while the restriction is absent. Passing examples do not resolve that mismatch. + ### Applying a label has no automation action **Hard stop:** no action in the catalog applies a label to a card. The **action** is what is missing, not the trigger: `sla_based` is in the event catalog, so "when the card goes overdue" is a perfectly good trigger with nothing to attach to. `get_automation_actions(pipe_id)` is the dynamic source of truth for what a given pipe offers; read it before planning a rule and do not assume a label action exists. @@ -278,7 +351,7 @@ Use this pattern for approvals, financial decisions, content publication, and an ### Other failure modes - **`simulate_automation` is AI-only.** Only `generate_with_ai` `action_id` accepted. For traditional rules, use `get_automation_logs` after the rule fires. -- **Async simulation result.** A `processing` response has no final result yet. Keep the `simulation_id` and read it with the `automationSimulation` query through `execute_graphql` (see [Steps — simulate](#steps--simulate-a-traditional-automation)). `get_automation_logs` requires a real automation ID, and another `simulate_automation` call starts a new simulation. +- **Async simulation result.** A `processing` response has no final result yet. Keep the `simulation_id` and read it with the `automationSimulation` query through `execute_graphql` (see [Steps: simulate an AI automation](#steps-simulate-an-ai-automation)). `get_automation_logs` requires a real automation ID, and another `simulate_automation` call starts a new simulation. - **`validate_ai_automation_prompt` returns `valid:false`.** Read `problems` (per-field) and `warnings`. Most common: prompt missing `%{internal_id}` reference, or `field_ids` overlap with prompt `%{id}` tokens. - **`create_automation` cycle detection.** Same-pipe `card_created` + `create_card` rejected with `"This automation can't be created! It would result in an endless card creation cycle."` Use a different trigger, target a different pipe, or use `update_card` instead. - **`create_automation` fails with unknown event/action.** Always run `get_automation_events` + `get_automation_actions` first; do not guess IDs. @@ -289,7 +362,7 @@ Use this pattern for approvals, financial decisions, content publication, and an - **`create_send_task_automation` fires immediately when `active=true`.** Pass `active=false` first if you want to wire it up before the rule starts firing. The 2026-04-16 orphaned-task incident is the cautionary tale. - **`update_automation` API asymmetry.** `create_automation` takes a top-level `active` param; `update_automation` requires `extra_input={"active": false}`. Pass `active` through `extra_input` when toggling on an existing rule. - **`action_repo_id` semantics.** For cross-pipe actions (`create_connected_card`, `create_card` into another pipe), this is the **destination** pipe, not the source. -- **Simulation reuses real rule params.** Before simulating, call `get_automation` to read `event_params` and `action_params` of a working rule and pass them verbatim. Don't hand-craft params. +- For simulation inputs, follow [Steps: simulate an AI automation](#steps-simulate-an-ai-automation). Use only the saved input fields. Remove response-only metadata. - **`field_map` uses slug in `fieldId`.** Preflight rejects non-numeric `fieldId` before GraphQL; slugs (e.g. `due_date`) used to surface as `INTERNAL_SERVER_ERROR`. Recovery: `get_start_form_fields` / `get_phase_fields` → use `internal_id`. - **Unknown `field_map` `fieldId`.** `create_automation` preflight fails with the offending id when the destination field is not on the action pipe. Re-discover ids on `action_repo_id` (not only the trigger pipe for cross-pipe actions). - **Used `update_card_field` operation for a rule.** That tool updates one card by **slug**; automations need `create_automation` + `field_map` with numeric `fieldId`. diff --git a/plugins/pipefy/skills/pipefy-automations/references/cli.md b/plugins/pipefy/skills/pipefy-automations/references/cli.md index 233a47815..3bb7f1605 100644 --- a/plugins/pipefy/skills/pipefy-automations/references/cli.md +++ b/plugins/pipefy/skills/pipefy-automations/references/cli.md @@ -30,3 +30,20 @@ Destructive deletes require `--yes`; there is no confirmation token. and `pageInfo.hasNextPage`; use the next cursor until no page remains. Use `--condition` on `pipefy automation create` and `pipefy automation update` for the shared condition payload. + +## Create an AI automation inactive + +Use the shared "Create an AI automation inactive" recipe before this command. +Replace the example pipe and field ids with ids from the pipe. +Use the selected event and its parameters: + +```bash +pipefy automation create --pipe 67890 --name "Summarize intake" --event-id card_created --action-id generate_with_ai --no-active --extra '{"action_params":{"aiParams":{"value":"Summarize %{900000102} into the summary field.","fieldIds":["900000101"],"skillsIds":[]}},"condition":{"expressions":[{"structure_id":0,"field_address":"","operation":"","value":""}],"expressions_structure":[[0]]}}' --json +``` + +Read the returned `createAutomation.automation.id` with `pipefy ai-automation get `. +Activate it only when the shared recipe permits activation: + +```bash +pipefy ai-automation update --pipe 67890 --patch-active --json +``` diff --git a/plugins/pipefy/skills/pipefy-process-design/SKILL.md b/plugins/pipefy/skills/pipefy-process-design/SKILL.md index 32f0d9989..ee3e5c65e 100644 --- a/plugins/pipefy/skills/pipefy-process-design/SKILL.md +++ b/plugins/pipefy/skills/pipefy-process-design/SKILL.md @@ -1,128 +1,257 @@ --- name: pipefy-process-design description: > - Use this skill ONLY when the user explicitly asks for help designing - or architecting a process ("help me design", "what's the best structure", - "how do I organize this flow?"). For direct execution requests - ("create a pipe for X", "build a reimbursement process", or any message - with a detailed spec), skip this skill and execute directly using the - domain skills (pipes-and-cards, automations, etc.). -tags: [pipefy, process-design, orchestration, pipes, consulting] + Designs a Pipefy process with the user before anyone builds it. Finds the + start, the end states, the steps and owners, the decision rules with exact + boundary values, the exceptions and the data. Compares a native rule, an AI + automation, an AI agent, an integration and human work for each step. + Returns a process specification that a builder can use. Use it when the user + wants to think a process through ("help me design", "how should this flow + work", "I do not know who approves"). Use it also when a request to build a + whole process still has an open business decision. Use it when the user + wants advice and no change, or brings a specification to check. Not for one + part such as a field, a phase or one automation (pipefy-building). Not for + building a process that is already specified (pipefy-building). Not for + diagnosing an existing pipe (pipefy-process-intelligence) or sizing the + return of a change (pipefy-process-impact). +tags: [pipefy, process-design, specification, consulting] --- -# Pipefy Process Design +# Design a Pipefy process -Read the [MCP reference](references/mcp.md) or [CLI reference](references/cli.md) for the surface you are using. Load only the relevant reference. +This skill helps the user design a process before anyone builds it. The result is a process specification: the business decisions that a builder needs to build the process. -This skill activates when the user wants **consulting help** to design a process — not when they want you to build one. If the user already knows what they want (gave you phases, fields, a spec, or a clear use case), **do not use this skill**. Execute directly. +When an organization is connected, read the [MCP reference](references/mcp.md) or the [CLI reference](references/cli.md) for the reads in step 1. Load only the reference for your surface. --- -## When to use vs when to execute +## When to use -| Signal | Response | -|--------|----------| -| "Help me design a process for X" | **Use this skill** — consulting mode. | -| "What's the best structure for Y?" | **Use this skill** — architecture guidance. | -| "Create a pipe for X" | **Skip this skill** — route via `pipefy-building`, then the domain skill. | -| User provides phases, fields, or a spec | **Skip this skill** — the spec IS the plan. Route via `pipefy-building`, then build. | +- The user wants to think a process through. Examples: "help me design a purchasing process", "what is the best structure for incident handling", "I do not know who approves". +- The user asks to build a whole process, and a business decision that changes the build is still open. Examples: who approves, which value routes a case, what happens on a rejection. A verb such as "create" or "build" does not close the decision. +- The user wants advice and no change. +- The user brings a specification and wants a check. ---- +## When not to use + +Read `pipefy-building` for these requests. It sends each one to the skill that owns it. + +- One part, such as a field, a phase, one automation, or one agent. +- A whole process that is already specified: every blocking field of the [process specification](#process-specification) has a value. +- A deletion, or a change to a part that already exists. -## Prerequisites +To diagnose an existing pipe, read `pipefy-process-intelligence`. To size the return of a change, read `pipefy-process-impact`. -- Understand the user's industry and use case before advising structure. -- Always search for existing pipes in the org before recommending a new one (`search_pipes`). +## What this skill writes + +- This skill does not write to Pipefy. It ends with a specification. +- A request for advice only gets advice. Write nothing and build nothing. +- A design works without a connected organization. Design from the conversation, and say that you did not check the existing pipes for reuse. +- When the user asks to build what you designed, read `pipefy-building`. It sends the build to the domain skills, or to a skill in your catalog that builds a whole process from a specification. Give that skill the specification. --- -## Discovery phase +## Ask in proportion to what is missing -1. **Research existing org structure:** +- When the user brings a specification, do not interview. Compare it with the specification fields. Equal content in another format counts. Do not ask the user to rewrite it. +- When every blocking field has a value, return the specification in the contract format. Mark each value that you added as an assumption. +- When a blocking field has no value, ask only for that field. Ask all of them in one message, with a proposed answer for each. +- Do not ask again about a decision that the user or the specification already settled. +- Keep the user's names for phases, fields, and roles. +- When the user does not know the process, propose a structure and two alternatives. Ask 5 questions or fewer in a turn. Each question has a proposed answer. +- Use documents that the user gives and the pipes you can read before you ask. - Operation: `search_pipes pipe_name=""` (empty search returns all visible pipes) - Operation: `get_organization organization_id=` +## Steps -2. **Understand the process intent:** - - What triggers a new case? (form submission, email, manual) - - Who are the actors? (submitter, approver, ops team) - - What are the key decision points? (approve/reject, escalate, auto-close) - - What data needs to be tracked? (fields per phase) - - Are there related processes that should be connected? (use relations) +1. **Read what exists.** With a connected organization, list the pipes before you propose a new one. When a pipe already does part of the work, read what runs there and propose to reuse it. Without a connected organization, skip this step. -3. **Identify the right Pipefy components:** + | Operation | Read-only | Purpose | + |-----------|-----------|---------| + | `search_pipes` | Yes | List pipes within the caller's memberships and the per-organization cap. Inspect `search_limits` before declaring reuse discovery complete. | + | `get_organization` | Yes | Read the organization that holds the pipes. | + | `get_pipe` | Yes | Read the phases and fields of a pipe that you can reuse. | + | `get_automations` | Yes | Read the rules that already run in that pipe. | + | `get_ai_agents` | Yes | Read the AI agents that already run in that pipe (pipe `uuid`). | - | Need | Component | - |------|-----------| - | Workflow stages | Pipe + Phases | - | Structured data per stage | Phase fields | - | Reference/lookup data | Database table | - | Cross-process linkage | Pipe relation | - | Automatic actions | Automation rule | - | AI-driven processing | AI automation or AI agent | +2. **Find the blocking fields.** Compare the request with the [process specification](#process-specification). Sort each field into three groups: the user gave it, you can propose it, or it stays open. ---- +3. **Propose a structure and alternatives.** When the structure is open, give one proposal and two concrete alternatives. For each one, give the cost, the risk, and the effect. The cost is the parts to build and maintain, and AI credits when known. The risk is what goes wrong, and who sees it. The effect is the work that it removes from the team or adds. Recommend one, and give the reason. + +4. **Choose the Pipefy part for each step.** Use the [selection table](#choose-the-pipefy-part-for-each-step). + +5. **Review the specification.** Use the [review questions](#review-questions). Ask only the ones that change the build. + +6. **Return the specification and the summary.** Use the [output format](#output). + +Read [references/process-specification.md](references/process-specification.md) when the user asks for a written specification, or when more than three decisions stay open. It has two complete specifications in the contract format. + +Read [references/feature-selection.md](references/feature-selection.md) when two Pipefy parts fit the same step, or when the user asks why you chose one part and not another. ## Design principles -- **Start with the outcome.** What does "done" look like for this process? -- **Name phases for states, not actions.** "Under Review" not "Review It". -- **Keep the start form minimal.** Only ask for data the requester can provide on day 1. -- **Use required fields sparingly.** Every required field is a blocker. -- **Design for the exception.** Add a "Blocked" or "On Hold" phase for edge cases. -- **Automate the obvious.** If a transition always happens under the same condition, it should be an automation, not a manual step. +- **Start with the outcome.** What does "done" look like for a case? +- **Name phases for states, not actions.** "Under review", not "Review it". +- **Keep the start form short.** Ask only for the data that the requester has on day 1. +- **Make a field required only when a decision reads it.** Each required field can stop a card. +- **Plan for the exception.** A rejection, a pause for a fix, and a time limit each need a path. +- **One phase is one state of the case.** A participant is an owner of a phase, not a separate pipe, unless that work has its own cases. + +--- + +## Process specification + +The specification holds business decisions, not Pipefy ids. The builder finds ids and product limits when it builds. The builder never finds a business decision: it returns the decision to the user as a question. + +| Field | What it holds | Who writes it | Blocks the build | Default when absent | +|---|---|---|---|---| +| Objective | The result that "done" gives, and what is out of scope. | User. The design skill writes it down. | Yes | None. Propose one sentence from the request and ask the user to confirm it. | +| Start trigger | What creates a case: a start form, an email, another pipe, a portal page. | User | Yes | A requester fills the start form. | +| End states | Each result that closes a case, with what the case must hold at that point. | User | Yes | One end phase for success. Add one end phase for refusal when a step can refuse. | +| Steps and owners | The ordered states of a case. Each state has one owner (a role), the person who decides, and the person who handles its exceptions. | Design skill proposes. User confirms. | Yes | The phases the user named. The owner is the role the user named, else the pipe members. | +| Decisions | For each branch: the field it reads, the operator, and the value. Also the result at the exact boundary value, the result for an empty field, and the destination. | User | Yes, but only for the branch | No automatic rule. A person in that phase decides. | +| Parallel work | The steps that run at the same time, and the join rule: all results, any result, or a stated combination. Also what happens to open work when one result ends the case. | User | No | No parallel work. Steps run in sequence. | +| Exceptions | Rejection: ends the case, or pauses it until someone fixes it. Time: a reminder only notifies, a deadline moves, escalates or reassigns. Correction: return point, owner, and the condition to continue. | User | No | A rejection pauses the case in an on-hold phase. A time limit is a reminder. A correction returns to the step that owns the missing data. No retry limit. | +| Data | For each field: name, type, source, author (role), the step where it is filled, and when it is required. | Design skill proposes. User confirms. | Yes, for a field that a decision reads | Only the fields that decisions and end states read. A field is required only when a decision reads it. | +| Platform choices | For each step: the Pipefy part that does it, one alternative, the reason in one line, and the existing part to reuse. | Design skill | No | The least complex native option in the selection table. No AI without an explicit yes. | +| Constraints | Limits the user states: no AI, no email outside the company, who may approve, data that must not leave Pipefy. | User | No | None stated. | +| Authorization | One level: advise only, build, build inactive, or publish. List each permitted external effect separately. | User | No | Advise only until the user requests a build. A build request defaults to build. No external effects. | +| Assumptions | Values that the design skill or the builder chose and the user did not confirm. | Design skill and builder | No. A rule that reads a business assumption starts inactive and waits for the user's answer. | Empty. Link each assumption to its dependent work. | +| Pending items | Open decisions, each with the work or activation that it blocks. | Design skill and builder | Only the named work or activation | Empty. | +| Acceptance examples | Two to five cases: input, expected path, final state. Include the boundary value, the empty value, and one exception. | Design skill proposes. User confirms. | No | One example for each decision branch, plus its boundary value and its empty value. The builder reports each example it did not check. | + +Authorization levels: + +- **Advise only.** No write. Use it when the user has not requested construction, or explicitly says to change nothing. +- **Build.** Create the parts of a new process with its automations and AI agents on. This is the default for a build request. A new pipe starts without cards. +- **Build inactive.** Create the parts, and keep every automation and AI agent inactive. Use it when the user asks for it. +- **Publish.** Also publish what has a draft state: a sub-portal, an integration flow. Create an HTML interface only when the user asks for one by name. + +External effects are separate permissions, not a build level. Each webhook, email outside the company, and member invitation needs its own yes. Record each permitted effect without changing the build level. This permission does not activate or publish unrelated parts. + +Without the publish level, a sub-portal stays unpublished and an integration flow stays a draft. Do not perform an external effect without its permission. + +At the build level, the builder creates these rules inactive. In this list, a rule is an automation or an AI agent. + +- A rule that the build adds to a pipe that existed before this conversation, when the pipe has cards that the rule can match. +- A rule that runs on a time limit or a schedule, on a pipe that has cards. +- A rule that reads an unconfirmed business assumption (a pending item). +- A rule that moves a card through a phase connection that does not exist yet. + +For the first two kinds, read the rule again. Compare it with the specification. If it matches and no other off case applies, activate it without another yes. An inactive request, an unconfirmed assumption, or a missing connection keeps the rule off. + +For traditional automations, use the "Start state" section in `pipefy-automations`. For AI automations, use its "Create an AI automation inactive" section. For AI agents, use the "Active lifecycle" section in `pipefy-ai-agents`. If a missing connection prevents creation even with `active=false`, record `skipped`. Wait for the connection before creating the rule. Never report a rejected creation as `created inactive`. + +The specification records acceptance examples and pending work. Report an unchecked example as pending. Do not declare the process ready until its acceptance examples pass and no required work remains. + +Rules that connect the design skill and the builder: + +- A specification holds no ids. Do not invent an id to make a specification look complete. +- A complete specification gets no second questionnaire. The builder asks only about pending items. +- A pending item blocks only the dependent work or activation. The builder continues the independent work. +- If a rule reads an unconfirmed business assumption, record it as a pending item for that rule. Create it inactive. Activate it only after the user confirms the decision. +- "No AI" in Constraints removes AI from Platform choices. AI enters Platform choices as confirmed only after an explicit yes from the user. The user's confirmation of the specification is that yes for its AI recommendations. + +Specification template (one line for each field): + +```text +Objective: +Start trigger: +End states: +Steps and owners: +Decisions: +Parallel work: +Exceptions: +Data: +Platform choices: +Constraints: +Authorization: +Assumptions: +Pending items: +Acceptance examples: +``` --- -## Common patterns +## Choose the Pipefy part for each step -### Linear approval flow -`Submission → Under Review → Approved / Rejected → Done` -- Start form: requester fills details. -- "Under Review" phase: approver field + due date. -- Automation: notify approver on card creation. +Use the least complex part that gives the result and the controls the user needs. Before you propose a new part, check what already runs in the pipe and reuse it. -### Multi-stage pipeline -`Intake → Triage → In Progress → Testing → Deployed` -- Each phase has role-specific fields. -- Automations advance cards on condition. -- SLA fields track time-in-phase. +| Part | Choose it when | Ask before you choose it | Do not choose it when | +|---|---|---|---| +| Traditional automation | An event, a test on fields, and a supported action describe the step. | Does the native rule cover the whole requirement, including the exact boundary value and the empty value? | The step needs judgment that no field test can express. | +| AI automation | The step reads card fields or an attachment on one event. It writes a fixed output: a category, a summary, or a value from a document. Recommend it for that step. | Which representative examples show the quality that the team accepts? What happens when the output is wrong? | A field test decides the step. Use a traditional automation. | +| AI agent | The step needs process context, an action that an AI automation cannot take, or a trigger that only an agent has. Actions: move a card, create a card, ask a person to review the result, call a tool on an MCP server. Recommend one agent with one responsibility and 1 to 5 behaviors. | Which context, which action limits, and which human review does this responsibility need? | One prompt with fixed output fields does the work. Use an AI automation. The step runs on a schedule: `scheduler` is never an agent trigger. | +| Integration | Another system owns the data or the action. | Is one call on a card event enough (a webhook)? Or does the work need several steps, a schedule, or routing (an integration flow)? | The external action happens one time only. Do not create a permanent flow for it. | +| Human work, field condition, or formula | A person must judge with no fixed test, or automation costs more than it returns. A field condition shows or requires a field inside a phase. A formula field calculates a value from other fields. | Can a field condition, a formula, or a clear task for a named owner solve the problem? | A rule with a field test does the same work with less effort. | -### Hub-and-spoke (related processes) -- Central "intake" pipe connected via pipe relation to domain-specific pipes. -- Child cards created automatically via automation when parent moves to "Escalated". +Rules for the choice: + +- Native rule before AI. Do not stack a rule and AI on the same step. If a rule leaves manual work, describe that work as a separate step. Recommend AI for that step when the AI criteria apply and the user did not exclude AI. +- Integration and AI are separate choices. A flow can read data from another system, an AI step can read the content, and a rule can route the result. +- Repeated work alone does not prove a need for AI. A document to read does not prove a need for a new agent. +- A missing automation or agent is not an improvement by itself. Some results need human work, a field condition, or a formula. +- For each choice, write the work it removes, the alternative, and the cost: maintenance, credits when known, and the effect of an error. +- When the user did not exclude AI and an AI row fits the step, recommend that AI part. Give the reason, the test, and what happens when the output is wrong. The user's confirmation of the specification authorizes its AI recommendations. Neither skill asks again for those parts. Until confirmation, record each AI part as recommended, not confirmed. --- -## Output format +## Review questions + +Use these questions to check a specification. Ask the user only the ones that change the build, in one message. Ask the user to confirm the specification, including its AI recommendations. That confirmation authorizes those AI parts. Do not ask again before the build. + +| Question | It finds | Change in the specification | +|---|---|---| +| What creates a case? Can a case start in another way, such as an email or another pipe? | A start path with no data rules | Start trigger lists each source and the data it must bring. | +| For each decision, what happens at the exact boundary value, and when the field is empty? | A branch with no result at the edge | Decisions get the boundary result and the empty result. Acceptance examples test both. | +| Can two conditions be true at the same time, or can a case match no condition? | Overlaps and gaps | Decisions get one result for each case, plus a default path. | +| Does work run at the same time? Does the next step need all results, any result, or a stated combination? | A missing join rule | Parallel work gets its join rule. | +| When one parallel result ends the case, what happens to the open work? | Open work with no owner | Parallel work gets its cancellation rule. | +| Is a rejection a normal end, or does it pause the case until someone fixes it? | A rejection that should be an interruption, or the opposite | Exceptions say "ends" or "pauses". End states or an on-hold phase change. | +| Does a time limit only remind, or does it move, escalate, or reassign the case? | A reminder that should be a deadline | Exceptions name the action and the new owner. | +| When work returns for correction, where does it return, who fixes it, and what lets it continue? | A loop with no exit | Exceptions get the return point, the owner, and the exit condition. Do not invent a retry limit. | +| Is this the process today, the target process, or an optional improvement? | Proposals recorded as facts | Assumptions and Platform choices mark what the user did not confirm. | +| Which Pipefy part does each step? Is each activity really a phase, and is each participant really a separate pipe? | Too many phases or pipes | Platform choices get one part for each step, with reuse. | +| Do you confirm this specification, including its AI recommendations? | AI recorded without a yes | Confirmation marks those AI lines as confirmed. A rejected recommendation uses its alternative. | +| Can a new rule match cards in a pipe from before this conversation? Does it read an unconfirmed assumption? | A rule that acts before the builder checks it | Platform choices record the initial state, the reason, and when activation can proceed. | -After the design consultation, produce a concise summary: +--- -``` -Process: -Phases: [list] -Start form fields: [list with types] -Key automations: [list] -Related processes: [list or "none"] -Manual steps in Pipefy: [parts no operation creates, or "none"] -Impact: [one line: time this design returns to the team against a fully manual run of the same flow; if a phase exists only for human triage, what an automation or an AI agent would change there. Do not start a pipe diagnosis.] -Next step: [execute with pipes-and-cards skill? or more questions?] +## Output + +End the design with the specification in the template format, then this summary: + +```text +Process: +Pending items: +Manual steps: +Impact: +Next step: ``` -Manual steps name the parts of the design that only the Pipefy UI creates: phase connections other than the links a new phase gets to its neighbours (`pipefy-pipes-and-cards`), email templates (`pipefy-members-email-webhooks`), and rules that apply a label (`pipefy-automations`). Keep Impact to one line. Do not invent volume, hourly cost, or lead time; name every missing number and ask for all of them in one question. For a fuller justification, read `pipefy-process-impact`. +- Say that the specification is ready to build only when every blocking field has a value. Otherwise name each field that is missing. +- When the user wants to build next, give `pipefy-building` the specification. State that the build activates the new parts. Name each rule that starts inactive or stays skipped, with its reason and next action. ---- +Manual steps name the parts of the design that only the Pipefy UI creates: + +- Phase connections other than the links that a new phase gets to its neighbours (`pipefy-pipes-and-cards`). +- Email templates (`pipefy-members-email-webhooks`). +- Rules that apply a label (`pipefy-automations`). + +Keep Impact to one line. Do not invent volume, hourly cost, or lead time; name every missing number and ask for all of them in one question. For a fuller justification, read `pipefy-process-impact`. ## Success criteria -- User has clarity on phases, fields, and automation triggers before execution starts. -- No duplicate pipes created (checked via `search_pipes`). -- The design is buildable with available operations (no features promised that don't exist). +- Every blocking field of the specification has a value, or it is a pending item with the part it blocks. +- Each step has one Pipefy part, one alternative, and a reason. No AI is a confirmed choice without an explicit yes. +- The design reuses the pipes and parts that already exist, or it says that nobody checked them. +- The design promises only parts that Pipefy can build, and it names the manual steps. +- Nothing was written to Pipefy. ## See also -- `pipefy-building` — for execution / build asks, read the router then the domain skill (do not expand this consulting skill into a build playbook). -- `pipefy-pipes-and-cards` — execute the design once finalized. -- `pipefy-automations` — add automation rules to the new pipe. -- `pipefy-process-intelligence` — analyze an existing process for improvement (distinct from designing new). -- `pipefy-process-impact` to justify a material change in full; this skill only emits the Impact line. +- `pipefy-building`: read it when the user asks to build. It routes the build. +- `pipefy-pipes-and-cards`: phases, fields, field conditions, and phase connections. +- `pipefy-automations`: traditional and AI automations, and their limits. +- `pipefy-ai-agents`: AI agents and their behaviors. +- `pipefy-process-intelligence`: diagnose an existing pipe. This skill designs a new one. +- `pipefy-process-impact`: justify a material change in full. This skill only emits the Impact line. diff --git a/plugins/pipefy/skills/pipefy-process-design/references/cli.md b/plugins/pipefy/skills/pipefy-process-design/references/cli.md index 3401132f7..e16014210 100644 --- a/plugins/pipefy/skills/pipefy-process-design/references/cli.md +++ b/plugins/pipefy/skills/pipefy-process-design/references/cli.md @@ -1,3 +1,15 @@ # CLI reference -For `search_pipes`, use `pipefy pipe list` as documented in `pipefy-pipes-and-cards`. For `get_organization`, use `pipefy org get`. Consult the domain skill selected by `pipefy-building` when the design is ready for execution. +| Operation | Command | +|-----------|---------| +| `search_pipes` | `pipefy pipe list --name ` | +| `get_organization` | `pipefy org get ` | +| `get_pipe` | `pipefy pipe get --json` | +| `get_automations` | `pipefy automation list --pipe --json` | +| `get_ai_agents` | `pipefy agent list --repo --json` | + +`--repo` takes the pipe UUID that `pipefy pipe get` returns, not the numeric pipe id. + +`pipefy automation list` returns one page of up to 50 rules. While `pageInfo.hasNextPage` is true, run it again with `--after `. + +When the design is ready to build, read `pipefy-building`. It names the domain skill for each part. diff --git a/plugins/pipefy/skills/pipefy-process-design/references/feature-selection.md b/plugins/pipefy/skills/pipefy-process-design/references/feature-selection.md new file mode 100644 index 000000000..35620529b --- /dev/null +++ b/plugins/pipefy/skills/pipefy-process-design/references/feature-selection.md @@ -0,0 +1,124 @@ +# Feature selection: criteria and edge cases + +This file adds to the selection table in the skill: the limits of each part, and the cases where the first choice is often wrong. + +Contents: + +- [How to write a choice](#how-to-write-a-choice) +- [Traditional automation](#traditional-automation) +- [AI automation](#ai-automation) +- [AI agent](#ai-agent) +- [Integration](#integration) +- [Human work, field condition, or formula](#human-work-field-condition-or-formula) +- [Other parts of a design](#other-parts-of-a-design) +- [Edge cases](#edge-cases) + +--- + +## How to write a choice + +Write one line for each step in Platform choices: + +```text +: . Alternative: . Reason: . Cost: . Reuse: . +``` + +- Name the work that the part removes. "Moves the card when the review is done" is a result. "Adds an automation" is not. +- Name one alternative, also when the choice is clear. The user can then see what you did not choose. +- For an AI part, also write the test and the effect of a wrong output. Until the user confirms the specification, write "recommended, not confirmed" in the line. After that confirmation, write "confirmed". + +--- + +## Traditional automation + +- **Boundary values.** The native number tests are "greater than" and "less than". A rule for "5,000.00 or more" uses "greater than 4,999.99", or the other path uses "less than 5,000.00". Write the boundary result in Decisions so that the builder can test it. +- **Empty values.** Give the empty case its own result. Make the field required in the phase that collects it, or add a rule with the `blank` test. +- **Phase moves.** A move rule needs a connection between the two phases. A new pipe connects each phase only to the phases beside it. Other connections are a manual step in the Pipefy interface. Keep the dependent rule off until the connection exists. If creation fails even with `active=false`, record `skipped` instead of `created inactive`. See `pipefy-pipes-and-cards`. +- **Labels.** No automation action applies a label to a card. Propose a status field that a rule fills, or a manual step. See `pipefy-automations`. +- **Email.** A rule that sends email needs an email template. Only the Pipefy interface creates a template. Email to an address outside the company is an external effect. +- **Event and action pairs.** Not every event works with every action. Before you promise a rule, check the pair in `pipefy-automations`. + +Cost: low maintenance. A wrong rule moves or changes cards without a person. Ask for acceptance examples at the boundary value and the empty value. + +--- + +## AI automation + +- **When to recommend it.** The step reads card fields or an attachment on one event. It writes a fixed output: a category, a summary, or a value from a document. Recommend an AI automation for that step. When a field test decides the step, recommend a traditional automation. +- **Fixed output.** The output goes into fields that you can name before the build. When you cannot name the output fields, the step is not an AI automation. +- **Test.** Ask for representative examples, such as 20 real documents, and the quality that the team accepts. The test is part of the recommendation. +- **Wrong output.** Say what happens when the output is wrong: a person checks it in the next phase, or a field condition asks for a review. +- **Credits.** An AI automation uses AI credits. Give the number of runs when the user knows the volume, so that the user can see the cost. +- **Trigger.** An AI automation runs on one card event, such as a new card or a move to a phase. When the step needs a trigger that an AI automation does not offer, recommend an AI agent. Before you promise a trigger, check the pair in `pipefy-automations`. +- **Consent.** Include the recommendation in the specification. The user's confirmation of that specification is the yes. Nobody asks again for that AI part. Without confirmation, the line stays "recommended, not confirmed". + +--- + +## AI agent + +- **When to recommend it.** The step needs process context, an action that an AI automation cannot take, or a trigger that only an agent has. Recommend one agent with one responsibility for that step. +- **Actions.** An agent can update a card, move a card, or create a card or a connected card. It can also create a table record and send an email template. It can ask a person to review the result (`human_validation`) and call a tool on an MCP server (`mcp_tool`). +- **Start.** An agent starts on one of these triggers, without a conversation. See `pipefy-ai-agents`. + - A card enters a phase, or a card leaves a phase. + - A field is updated, or a card is created. + - An alert is triggered (`sla_based`). + - An email is received. + - All connected cards move to a phase. + - An HTTP response is received. + - An interface button is clicked. +- **No schedule.** `scheduler` is never an agent trigger. For a step on a schedule, use a traditional automation or an integration flow. +- **Scope.** Give one agent one responsibility. An agent has 1 to 5 behaviors. When the work needs more, split the responsibility. +- **Action limits.** Name the actions the agent may take. An action that approves, rejects, pays, or sends a message outside the company needs a human review before it runs. +- **Not an agent.** When one prompt with fixed output fields does the work, use an AI automation. It is less to maintain and easier to test. +- **Consent.** The user's confirmation of the specification authorizes its AI agent recommendation, as it does for an AI automation. + +--- + +## Integration + +| Need | Part | Why | +|---|---|---| +| One call to another system on a card event | Webhook | One call, no steps between. See `pipefy-members-email-webhooks`. | +| Several steps, a schedule, routing, or a connected app | Integration flow (iPaaS) | The flow holds the steps and the connection. See `pipefy-ipaas`. | +| An action that happens one time only, such as a data import | No permanent part | Do the action one time. A permanent flow is maintenance with no return. | + +- A webhook has no off state. It sends data to the other system on the first event. Treat it as an external effect. +- An integration flow has a draft state. It runs only after someone publishes it. + +--- + +## Human work, field condition, or formula + +- **Human work.** Give the step a named owner, the fields that the owner fills, and a time limit. A clear task for a named owner is a valid design. +- **Field condition.** Shows, hides, or requires a field inside a phase, based on another field. Use it for a reason that is required only on a rejection. +- **Formula.** A formula field calculates a value from other fields, such as a total. Use it before a rule that copies or adds values. +- **Low volume.** When a step runs a few times a month, a rule can cost more to maintain than the work it removes. Say so, and propose human work. + +--- + +## Other parts of a design + +| Need | Part | See | +|---|---|---| +| Reference data that many cases read, such as a vendor list | Database table | `pipefy-database-tables` | +| A link between cases in two processes | Pipe relation or table relation | `pipefy-relations` | +| A page where people outside the pipe start or follow a case | Portal page or sub-portal | `pipefy-portal-setup` | +| A standalone page with live data from pipes and tables | HTML interface, only when the user asks for one by name | `pipefy-html-interfaces` | + +--- + +## Edge cases + +| Case | First choice that is often wrong | Better choice | Why | +|---|---|---|---| +| The same manual step runs 200 times a week, and a field test decides it | AI automation | Traditional automation | Repeated work alone does not prove a need for AI. | +| A document arrives, and the team reads two values from it | New AI agent | AI automation with two output fields, recommended | A fixed output does not need an agent. | +| A rule routes most cases, and a small part stays manual | Rule and AI on the same step | Keep the rule. Describe the remaining work as another step. Recommend AI there when its criteria apply. | Each step has one part. The user can assess the remaining work separately. | +| The user said "no AI" | AI recommended | No AI in Platform choices | The constraint removes the recommendation. | +| An AI step must run every morning | AI agent on a schedule | A traditional automation or an integration flow on the schedule | `scheduler` is never an agent trigger. | +| Two teams review at the same time | A separate pipe for each team | Two decision fields in one phase, with a join rule | One phase keeps one case. Use child cards in a separate pipe only when each review has its own cases and owners. | +| A time limit must move the case to a new owner | A reminder | A deadline rule with the new owner named | A reminder only notifies. | +| A rejection must notify a vendor outside the company | An automation that sends email | An email template made in the Pipefy interface, plus a rule, after a yes to external effects | The template is a manual step, and the email is an external effect. | +| Each participant gets a pipe | One pipe for each role | One pipe, one phase owner for each role | A participant is an owner, not a process. | +| The pipe has no automation, so the design adds one | New automation | Human work, a field condition, or a formula, when they give the result | A missing automation is not an improvement by itself. | +| A step needs a data copy one time | Integration flow | One manual import | A permanent flow for a one-time action is maintenance with no return. | diff --git a/plugins/pipefy/skills/pipefy-process-design/references/mcp.md b/plugins/pipefy/skills/pipefy-process-design/references/mcp.md index 34a3572ba..5249b7086 100644 --- a/plugins/pipefy/skills/pipefy-process-design/references/mcp.md +++ b/plugins/pipefy/skills/pipefy-process-design/references/mcp.md @@ -6,8 +6,28 @@ search_pipes pipe_name="" ``` -An empty search returns all visible pipes. +An empty search lists pipes that the caller belongs to, with a cap per organization. Read `search_limits.max_pipes_per_org` before treating the result as complete. + +With a name filter, `pipes_truncated: true` means that matching results exceeded the cap. Without a name filter, the flag can also reflect membership scope. The flag alone does not prove that the cap removed results. + +Report unresolved access or truncation limits in the reuse assessment. Do not conclude that no reusable pipe exists outside the returned scope. Read [pipe listing limits](https://github.com/pipefy/ai-toolkit/blob/main/docs/mcp/tools/organization.md#why-counts-disagree) for the discovery rules. ```text get_organization organization_id= ``` + +For a pipe that the design can reuse: + +```text +get_pipe pipe_id= +``` + +```text +get_automations pipe_id= +``` + +Pass `after=` while `pagination.has_more` is true. + +```text +get_ai_agents repo_uuid= +``` diff --git a/plugins/pipefy/skills/pipefy-process-design/references/process-specification.md b/plugins/pipefy/skills/pipefy-process-design/references/process-specification.md new file mode 100644 index 000000000..8c0d4ba1d --- /dev/null +++ b/plugins/pipefy/skills/pipefy-process-design/references/process-specification.md @@ -0,0 +1,139 @@ +# Process specification examples + +This file has two complete process specifications in the contract format of the skill. Use the owning domain skills for implementation constraints. + +Contents: + +- [Example 1: purchase requests (Portuguese)](#example-1-purchase-requests-portuguese) +- [Example 2: vendor approval with parallel reviews](#example-2-vendor-approval-with-parallel-reviews) +- [Common structures](#common-structures) + +--- + +## Example 1: purchase requests (Portuguese) + +The user wrote in Portuguese. The specification keeps the user's language and the user's names for phases, fields, and roles. The labels follow the field order of the contract. + +```text +Objetivo: aprovar ou recusar pedidos de compra em até 3 dias úteis. Fora do escopo: emitir o PO no ERP. +Gatilho de início: o solicitante preenche o formulário inicial do pipe. +Estados finais: "Aprovado", com o número do PO preenchido; "Recusado", com o motivo preenchido. +Etapas e responsáveis: + 1. Solicitação: solicitante. + 2. Análise: comprador (papel: compras). Decide se o pedido segue. + 3. Aprovação gerencial: gerente da área do solicitante. Decide aprovar ou recusar. + 4. Aguardando documento: solicitante corrige. + 5. Aprovado (final). + 6. Recusado (final). +Decisões: + D1. Parecer de compras = Aprovar e Valor >= R$ 5.000,00 -> Aprovação gerencial. + Valor exatamente R$ 5.000,00 sobe ao gerente. + Valor < R$ 5.000,00 -> Aprovado sem gerente. + Valor vazio -> volta a Solicitação com a tarefa "informar valor". + D2. Parecer de compras = Recusar -> Recusado. + D3. Parecer de compras = Falta documento -> Aguardando documento. + D4. Decisão do gerente = Aprovar -> Aprovado. Recusar -> Recusado. +Trabalho paralelo: nenhum. +Exceções: + Rejeição: a recusa encerra o caso (Recusado). Não é interrupção. + Interrupção: falta de documento leva a Aguardando documento. O solicitante anexa e o caso volta a Análise. Sem limite de tentativas. + Tempo: Análise com mais de 2 dias úteis -> lembrete ao comprador. Só notifica, não move. +Dados: + Valor: moeda, formulário inicial, solicitante, obrigatório. + Centro de custo: seleção, formulário inicial, solicitante, obrigatório. + Parecer de compras: seleção (Aprovar, Recusar, Falta documento), Análise, comprador, obrigatório para sair de Análise. + Decisão do gerente: seleção (Aprovar, Recusar), Aprovação gerencial, gerente, obrigatório para sair da fase. + Motivo da recusa: texto longo, Análise ou Aprovação gerencial, quem recusa, obrigatório só quando o parecer ou a decisão é Recusar. + Número do PO: texto curto, Aprovado, comprador, obrigatório. +Escolhas de plataforma: + D1 a D4: automação tradicional (campo atualizado + condição sobre Valor e parecer). Alternativa: encaminhamento manual pelo responsável da fase. Motivo: a decisão lê campos e um valor fixo. + Motivo da recusa: condição de campo (mostra e exige só na recusa). Alternativa: campo sempre visível. + Lembrete: automação por prazo da fase (SLA). Alternativa: lembrete manual do gerente de compras. +Restrições: sem IA (política do financeiro). Nenhum e-mail para fora da empresa. +Autorização: construir. +Premissas: abaixo de R$ 5.000,00, compras aprova sem gerente. +Pendências: + P1. Quem recebe o lembrete de Análise nas férias do comprador. Bloqueia só o destinatário substituto do lembrete. + P2. Confirmar se compras aprova abaixo de R$ 5.000,00 sem gerente. Bloqueia só a ativação da regra de aprovação abaixo desse valor. +Exemplos de aceitação: + A1. Valor 4.999,99, parecer Aprovar -> Aprovado, sem passar pelo gerente. + A2. Valor 5.000,00, parecer Aprovar -> Aprovação gerencial. + A3. Valor vazio -> volta a Solicitação com a tarefa "informar valor". + A4. Parecer Falta documento -> Aguardando documento; depois do anexo, volta a Análise. + A5. Gerente escolhe Recusar sem motivo -> o card não sai da fase. +``` + + +--- + +## Example 2: vendor approval with parallel reviews + +This example has parallel work with a join rule and a cancellation rule. It also has a rejection that ends the case, and an AI recommendation that the user did not confirm. + +```text +Objective: approve a new vendor for payment in 10 business days or less. Out of scope: contract signature. +Start trigger: a buyer fills the start form with the vendor data and three documents. +End states: Approved, with a vendor code. Rejected, with the reason of the reviewer who rejected. +Steps and owners: + 1. Intake: buyer. + 2. Document check: procurement analyst. Decides if the document package is complete. + 3. Reviews: Legal reviewer and Finance reviewer, at the same time. + 4. Vendor setup: procurement analyst writes the vendor code. + 5. Approved (end). + 6. Rejected (end). + 7. On hold: buyer fixes the documents. +Decisions: + D1. Document check: all three documents attached -> Reviews. One or more missing -> On hold. + D2. Expected annual spend below 10,000.00 -> Finance decision = Not required. At exactly 10,000.00, Finance reviews. + Empty spend: not possible, the start form requires it. + D3. Legal = Approved AND (Finance = Approved OR Finance = Not required) -> Vendor setup. P2 blocks activation. + D4. Legal = Rejected OR Finance = Rejected -> Rejected. +Parallel work: Legal and Finance review in the same phase, at the same time. Join: both results. Not required counts as a result only after confirmation (P2). + Cancellation: when one reviewer rejects, the case moves to Rejected and the other review stops. +Exceptions: + Rejection ends the case. It does not pause it. + A missing document pauses the case in On hold. The buyer attaches it and the case returns to Document check. No retry limit. + Time: Reviews for more than 3 business days -> reminder to both reviewers (notify only). + Time: Reviews for more than 7 business days -> deadline. The case goes to a new owner (see P1). +Data: + Expected annual spend: currency, start form, buyer, required. + Tax certificate, Bank letter, Signed form: attachments, start form, buyer, required for D1. + Legal decision: select (Approved, Rejected), Reviews, Legal reviewer, not required to leave Reviews. D3 requires Approved for Vendor setup. + Finance decision: select (Approved, Rejected, Not required), Reviews, Finance reviewer or the D2 rule. + Rejection reason: long text, Reviews, the reviewer who rejects, required when a decision is Rejected. + Vendor code: short text, Vendor setup, procurement analyst, required. +Platform choices: + D2: traditional automation when a card enters Reviews, with a spend condition. It sets Finance decision to Not required below 10,000.00. + Alternative: the Finance reviewer sets the field. + D3, D4: traditional automations on a decision field update, with conditions. Alternative: child cards in a separate review pipe. + Reason: two fields in one phase hold both results, and the rules read fields. + Rejection reason: field condition. Alternative: a field that is always visible. + Reminder at 3 days: automation on the phase time limit. Alternative: a manual follow-up. + Read the tax id and the expiry date from the tax certificate: AI automation, recommended. Alternative: the analyst reads the certificate. + Reason: the step reads a document on one event and writes two fields. Test: 20 sample certificates read correctly. + Wrong output: a wrong date goes to the analyst. State: recommended, not confirmed. The user did not confirm the specification with this recommendation. + Email to the vendor on rejection: email template and an automation that sends it. This is an external effect. +Constraints: only the Legal reviewer approves legal terms. Bank data does not leave Pipefy. +Authorization: build ("build it"). External effects: not allowed. +Assumptions: Finance = Not required counts as a Finance result in the join. +Pending items: + P1. Who owns the case at the 7-day deadline. Blocks only the deadline rule. + P2. Does Not required count as a Finance result in the join? Blocks only D3 activation. +Acceptance examples: + A1. After P2 is confirmed: spend 9,999.99, Legal Approved -> Vendor setup. Finance is Not required. + A2. Spend 10,000.00, Legal Approved, Finance empty -> the case stays in Reviews. + A3. Finance Rejected, Legal empty, rejection reason filled -> Rejected. The Legal review stops. + A4. Legal Rejected while Finance is open -> Rejected. The Finance review stops. + A5. Bank letter missing -> On hold. After the buyer attaches it -> Document check. +``` + + +--- + +## Common structures + +Use these structures as a start for a proposal. Change them to fit the decisions that the user gives. + +- **Linear approval.** Submission, Under review, then Approved or Rejected. The requester fills the start form. The review phase holds the approver's decision field. A rule routes the case on that field. +- **Multi-stage work.** Intake, Triage, In progress, Testing, Done. Each phase has the fields of its owner. Rules move a card when a field test is true. A phase time limit sends a reminder. +- **Central intake with related pipes.** One intake pipe receives every request. A pipe relation connects it to the pipes that do the specialized work. A rule creates a connected card when a case needs that work. Use this structure only when each related pipe has its own cases and owners.