Skip to content

docs: propose workflow readability improvements#663

Open
miyaontherelay wants to merge 1 commit intomainfrom
docs/workflow-readability-proposal
Open

docs: propose workflow readability improvements#663
miyaontherelay wants to merge 1 commit intomainfrom
docs/workflow-readability-proposal

Conversation

@miyaontherelay
Copy link
Copy Markdown
Contributor

@miyaontherelay miyaontherelay commented Mar 27, 2026

Summary

  • add a focused proposal doc for making Relay workflows more readable across YAML, TypeScript, and Python
  • cover canonical workflow shape, prompt externalization, structured outputs, agent profiles, reusable step templates, and render/lint tooling
  • suggest a phased rollout aimed at improving reviewability without losing functionality

Scope

  • docs only
  • no runtime or schema changes in this PR

Why

Workflow authoring is powerful today, but review readability still lags behind. This proposal lays out a concrete path to make workflows easier to skim, reason about, and evolve while preserving the current capabilities.

Very short outline

  1. Separate workflow structure from bulky prompt payloads
  2. Align YAML, TypeScript, and Python around one canonical workflow model
  3. Standardize step shape, naming, descriptions, and structured outputs
  4. Move runtime details into profiles/defaults instead of per-step noise
  5. Add render/lint/normalize tooling to improve reviewability

Copy link
Copy Markdown
Contributor

@devin-ai-integration devin-ai-integration bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

Open in Devin Review

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants