docs: card-phase ergonomics parity, skills, and README by adriannoes · Pull Request #285 · pipefy/ai-toolkit

adriannoes · 2026-06-03T18:43:00Z

Analytics pipe seeding (306996636) required execute_graphql for phase inventory and phase-local creates. Spec: .cursor/dev-planning/specs/archive/card-phase-ergonomics/ — Stack after #277 (closed).

Depends on: #284

Objective

Document the tool-first agent path so future runs skip GraphQL:

docs/parity.md, MCP pipes-and-cards + reports reference
pipefy-pipes-and-cards skill: Seed pipe across phases workflow
README tool count (152), CHANGELOG, marketplace ai-toolkit metadata

Improvements

Skills/CI lint align with shipped tool names.
Agents routed away from execute_graphql for these flows.

gbrlcustodio

Review: docs, skills, README (PR 6 of the card-phase stack)

Docs-only PR, so this reviews claim accuracy against the code that landed across the stack (verified at head 8f12168), plus link and anchor resolution and count consistency. The new tool docs, the report-filter example, and the @latest install refs all check out. Ten findings below, most-severe first: two broken references (a README link and a skill anchor), a misquoted validator error, and a tool-count table that does not reconcile with its own headline. The rest are internal contradictions and stale counts.

Verification notes: PIPEFY_TOOL_NAMES has exactly 152 entries, so the headline bumps and the parity table's 152 rows are correct; the report-filter example JSON passes the preflight validator unchanged; normalize_label_color accepts both #RGB and #RRGGBB; create_card's phase_id path merges both the phase and start-form field sets. marketplace.json is excluded per your note that the manifest is fixed downstream.

adriannoes · 2026-06-10T15:31:06Z

Thanks @gbrlcustodio — addressed through ff0b4ab: fixed the broken README link and skill anchor; reconciled tool counts (40 pipes & cards, 6 introspection → 152); aligned changelog/parity/skill wording with validator messages, CLI renames, and dual field-set filtering; added [0.2.0-beta.3].

Update parity matrix, MCP reference, CHANGELOG, pipefy-pipes-and-cards skill (seed across phases; prefer dedicated tools over execute_graphql); README tool counts and ai-toolkit marketplace metadata.

Update pipes-and-cards reference, parity matrix, skill, and changelog after dropping start_form_phase from get_pipe and renaming SDK get_phase.

Reconcile README tool counts to 152; fix broken skill anchor; align parity/changelog/skill wording with CLI renames, label hex validator, and create_card field-merge behavior; add 0.2.0-beta.3 section.

Ownership repoint and homepage/repository fields already landed on main; revert PR-local edits so this stack does not regress owner metadata. Co-authored-by: Gabriel Custódio <gabriel.custodio@pipefy.com>

…counts) Fix card create CLI examples to use positional PIPE_ID; align phase_id vs skip_elicitation wording with MCP behavior; drop duplicate beta.3 changelog section; correct README domain counts; extend report filter parity notes; reword migration and reports skill per review.

adriannoes · 2026-06-11T20:14:30Z

Thanks @Danielmoraisg — addressed in febf922 (branch rebased onto updated #284 / 26c86b3):

blocker/major: positional pipefy card create <pipe_id> everywhere; phase_id vs skip_elicitation aligned with pipe_tools.py
major: duplicate [0.2.0-beta.3] removed; README counts fixed (Automations & AI 23, Introspection 5)
minor/nit: report filter parity on all five paths; get_phase_cards before get_phase_cards_count; MIGRATION reworded to "earlier names of this repository"; reports skill uses "rejected before GraphQL"

Tests: uv run pytest -m "not integration" — 3071 passed.

Ready for merge once CI is green.

adriannoes added the enhancement New feature or request label Jun 3, 2026

adriannoes self-assigned this Jun 3, 2026

adriannoes requested review from dan-de-morais and gbrlcustodio June 3, 2026 18:43

adriannoes mentioned this pull request Jun 3, 2026

feat: card-phase ergonomics (inventory, create_card phase_id, review fixes) #277

Closed

7 tasks

adriannoes force-pushed the feat/card-phase-erg/5-report-filter-and-cli-label branch from 0b11025 to 01c4788 Compare June 9, 2026 21:36

adriannoes force-pushed the feat/card-phase-erg/6-docs-and-skills branch from 09f4f24 to 8f12168 Compare June 9, 2026 21:36

adriannoes mentioned this pull request Jun 9, 2026

feat(sdk): phase card reads, create_card phase_id/title, get_pipe inventory #281

Merged

gbrlcustodio mentioned this pull request Jun 10, 2026

feat(mcp,cli): create_card phase_id and title on CreateCardInput #283

Merged

gbrlcustodio reviewed Jun 10, 2026

View reviewed changes

Comment thread .claude-plugin/marketplace.json Outdated

adriannoes force-pushed the feat/card-phase-erg/5-report-filter-and-cli-label branch from 01c4788 to 293a18f Compare June 10, 2026 15:30

adriannoes force-pushed the feat/card-phase-erg/6-docs-and-skills branch from 8f12168 to ff0b4ab Compare June 10, 2026 15:30

adriannoes force-pushed the feat/card-phase-erg/5-report-filter-and-cli-label branch from 293a18f to d0260f5 Compare June 10, 2026 17:54

adriannoes force-pushed the feat/card-phase-erg/6-docs-and-skills branch from dd4c1a8 to 6f9248b Compare June 10, 2026 17:54

This was referenced Jun 10, 2026

refactor(mcp): extract pure plan_create_card_fields planner from create_card #290

Open

refactor(sdk,mcp,cli): enforce report filter and label color validation at SDK boundary #291

Merged

feat(mcp,cli): report filter preflight and CLI label hex #284

Merged

Danielmoraisg reviewed Jun 11, 2026

View reviewed changes

adriannoes force-pushed the feat/card-phase-erg/5-report-filter-and-cli-label branch from d0260f5 to 26c86b3 Compare June 11, 2026 20:06

adriannoes and others added 6 commits June 11, 2026 17:12

docs: card-phase ergonomics parity, skills, and agent workflow guidance

c881c5b

Update parity matrix, MCP reference, CHANGELOG, pipefy-pipes-and-cards skill (seed across phases; prefer dedicated tools over execute_graphql); README tool counts and ai-toolkit marketplace metadata.

docs: align card-phase stack with get_phase and startFormPhaseId

7e7c9c6

Update pipes-and-cards reference, parity matrix, skill, and changelog after dropping start_form_phase from get_pipe and renaming SDK get_phase.

docs: fix card-phase review nits (counts, anchors, changelog accuracy)

ca73aa9

Reconcile README tool counts to 152; fix broken skill anchor; align parity/changelog/skill wording with CLI renames, label hex validator, and create_card field-merge behavior; add 0.2.0-beta.3 section.

test(cli): refresh help golden for phase count and targets

d4b3222

fix(plugin): drop stale marketplace.json hunk from docs PR

ee7e376

Ownership repoint and homepage/repository fields already landed on main; revert PR-local edits so this stack does not regress owner metadata. Co-authored-by: Gabriel Custódio <gabriel.custodio@pipefy.com>

adriannoes force-pushed the feat/card-phase-erg/6-docs-and-skills branch from 6f9248b to febf922 Compare June 11, 2026 20:14

adriannoes merged commit e68b6e1 into feat/card-phase-erg/5-report-filter-and-cli-label Jun 11, 2026
2 checks passed

Conversation

adriannoes commented Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Objective

Improvements

Uh oh!

gbrlcustodio left a comment

Choose a reason for hiding this comment

Review: docs, skills, README (PR 6 of the card-phase stack)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

adriannoes commented Jun 10, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

adriannoes commented Jun 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

adriannoes commented Jun 3, 2026 •

edited

Loading