docs: add conditional steps documentation and skipped step styling

[jumski]

Add Conditional Steps and Error Handling

This PR introduces comprehensive support for conditional step execution and graceful error handling in pgflow. The new features allow workflows to adapt to runtime conditions and handle failures without stopping the entire run.

Key Features

• Pattern Matching: Control step execution with if/ifNot conditions using PostgreSQL's JSON containment operator
• Skip Modes: Configure what happens when conditions aren't met with fail, skip, or skip-cascade options
• Error Handling: Gracefully handle step failures with retriesExhausted: 'skip' for non-critical steps
• Type Safety: TypeScript types reflect optional dependencies when steps might be skipped

Visual Representation

Added a new step_skipped style to the D2 theme for visualizing skipped steps in flow diagrams.

Documentation

Added comprehensive documentation with:

• Overview of conditional execution and error handling
• Pattern matching syntax and examples
• Skip mode behaviors and use cases
• Error handling best practices
• Type safety considerations
• Visual diagrams showing different execution paths

These features enable more resilient workflows where non-critical steps can fail without stopping the entire process.

[changeset-bot]

🦋 Changeset detected

Latest commit: 39bc3af

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
@pgflow/core	Minor
@pgflow/dsl	Minor
pgflow	Minor
@pgflow/client	Minor
@pgflow/edge-worker	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[jumski]

• fix: optimize step skipping and improve concurrent task handling #613
• feat: add constraints for input patterns and improve cascade skip tests #611
• fix: archive task messages for skipped steps and handle late callbacks #609
• fix: improve condition handling and event emission for failed steps #607
• fix: correctly decrement remaining_deps for multiple skipped parents #606
• rename when_failed to when_exhausted for clarity #602
• feat: add support for skipped steps in client #601
• feat: add conditional flow execution and retry handling #600
• docs: add conditional steps documentation and skipped step styling #594 👈 (View in Graphite)
• feat: add conditional step execution with skip infrastructure #572 : 1 other dependent PR (#573 )
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 39bc3af

Command	Status	Duration	Result
nx test:types:health dsl	✅ Succeeded	12s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-03-17 19:23:17 UTC

[github-actions]

🔍 Preview Deployment: Website

✅ Deployment successful!

🔗 Preview URL: https://pr-594.pgflow.pages.dev

📝 Details:

• Branch: 01-14-add_docs_for_conditional_steps
• Commit: 989f263dfedbfc0d6d3c380f76d8c570c2732d08
• View Logs

_Last updated: _

[jumski]

Merge activity

• Mar 17, 7:20 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Mar 17, 7:22 PM UTC: Graphite rebased this pull request as part of a merge.
• Mar 17, 7:22 PM UTC: @jumski merged this pull request with Graphite.

[github-actions]

🚀 Production Deployment: Website

✅ Successfully deployed to production!

🔗 Production URL: https://pgflow.dev

📝 Details:

• Commit: 320a10629b272f9376336baa0b021707879da4b8
• View Logs

Deployed at: 2026-03-17T20:22:26+01:00