Guidance: building a pipe from a spec hits phase-connection and routing dead ends

[adriannoes]

Problem

Building a pipe from a process spec/flowchart via MCP hits hard stops that are easy to discover too late: phase connections are not editable via API, and field-value routing without AI has no reliable traditional-automation path. Existing skills do not give an end-to-end “spec → working pipe” playbook that fronts these limits.

Evidence

From live product testing against main:

• Created many phases/fields, then discovered move_card_to_phase fails for non-adjacent moves; tool error notes connections are not editable via API.
• Confirmed via search_schema (connection / phase inputs): no mutation to set phase connections (only unrelated connection-status inputs).
• Attempted field-updated → move automations (8 rules) that API accepted but never fired — see Automations: create accepts event×action combos that never fire #385.
• Default/phase-index surprises while laying out the flow — see Pipe build: create_phase index behavior is undocumented #391.
• Would have avoided a full failed automation round with clearer “build pipe” guidance: create pipe → phases/fields → warn connection limit → suggest routing (AI vs manual / UI).

Impact

Agents can create phases and fields but cannot wire a functional end-to-end flow purely via API. That blocks a strong MCP+AI use case (programmatic process setup) and burns time on dead automation patterns.

Status on dev

PARTIAL — pipefy-pipes-and-cards / process-design / automations skills already mention that phase connections / transition edges are UI-only. Empty create_pipe is already on dev. Still no cohesive “from spec/flowchart” playbook that sequences tools and states connection + routing limits up front. Org/pipe discovery gaps: #383, #384.

Upstream note (not a separate issue)

Phase connection mutations are an API product gap. Toolkit work here is guidance, clearer errors, and honest playbooks until/unless the API ships something like set-phase-connections. Route API asks to the platform team; keep this issue focused on MCP/skill/docs UX.

Possible directions (non-binding)

• Skill (or strengthen existing) “build pipe from spec”: ordered steps + explicit connection/routing limits + when to stop and use UI
• Stronger tool errors / docstrings when moves fail due to missing connections
• Cross-link discovery (Discovery: cannot list organizations I can access without an org ID #383, Discovery: org pipe listing vs pipesCount mismatch is unexplained #384) and automation silent-fail (Automations: create accepts event×action combos that never fire #385) from the playbook
• Do not pretend programmatic full wiring is possible until API exists

Related: #385, #391, #383, #384

Solution and acceptance criteria are decided when this issue is picked up.