fix: onboarding quickstart accuracy improvements by nthmost-orkes · Pull Request #930 · conductor-oss/conductor

nthmost-orkes · 2026-03-26T19:20:55Z

Summary

This PR fixes the most common onboarding failures new users encounter in the first 5 minutes. Addresses conductor-oss/getting-started#1–5, conductor-oss/getting-started#11–14, and conductor-oss/getting-started#31.

Changes

docs/quickstart/index.md

Java 21 requirement is never mentioned in the quickstart path getting-started#2 — Added prominent Java 21 prerequisite notice before "Start Conductor"
JavaScript SDK package name is wrong in quickstart docs getting-started#5 — Fixed JS SDK npm package name (conductor-javascript-sdk was wrong)
Python worker example uses 'while True: pass' — spins CPU at 100% getting-started#13 — Replaced while True: pass busy-wait in Python worker example with time.sleep(0.1) loop + explanatory comment
Docker 'Using Docker instead' section: cURL sync equivalent is incomplete getting-started#14 — Fixed curl equivalent for conductor workflow start --sync to use correct REST endpoint (POST /api/workflow/{name}/run) with correct headers and example output
Quickstart --sync output is a wall of JSON, doesn't match the 'expected output' shown in docs getting-started#11 — Updated expected output block to show realistic CLI output (with Auto-detected server: prefix and jq extraction example) instead of a clean JSON blob
Phase 3 replay example: jq pipeline broken due to 'Auto-detected...' prefix in CLI output getting-started#12 — Fixed jq pipeline in Phase 3 to strip the Auto-detected server: stderr prefix using 2>/dev/null | tail -1 before piping to jq

README.md

conductor server start downloads 608 MB with no upfront warning getting-started#3 — Added warning callout after conductor server start noting the ~600 MB one-time JAR download
conductor workflow create gives no success feedback, then 500 error on retry getting-started#4 — Added idempotency note after conductor workflow create explaining the expected error on duplicate create and how to use conductor workflow update

.github/ISSUE_TEMPLATE/bug_report.md

Bug report issue template uses Python code example in a Java-primary project getting-started#31 — Replaced Python-specific code example with a language-neutral "Code to reproduce" fenced block

Issue conductor-oss/getting-started#1 (404 on conductor-oss.org/quickstart)

The 404 persists because docs/quickstart/index.md is not yet merged. This PR resolves it upon merge.

Test plan

Review each diff section against the corresponding issue description
Verify docs/quickstart/index.md renders correctly in the docs site preview
Confirm bug report template renders correctly on GitHub Issues

🤖 Generated with Claude Code

…d troubleshooting - Fix two broken quickstart links in README.md (conductor-oss.org/quickstart -> docs.conductor-oss.org/quickstart/) - Add Node.js v16+ and Java 21+ to prerequisites in README.md - Add Java 21+ prerequisite to docs/quickstart/index.md - Add troubleshooting callout box for common issues (Java not found, port conflicts, Docker alternative)

- #2: Add prominent Java 21 prerequisite callout before Phase 1 / Start Conductor - #5: Fix JS SDK package name from @conductor-oss/conductor-client to conductor-javascript-sdk; add npm install command - #13: Replace busy-wait `while True: pass` with `time.sleep(0.1)` + import time (CPU yield between poll cycles) - #14: Update Docker cURL --sync equivalent to use correct synchronous endpoint /api/workflow/{name}/run

- #11: Replace clean JSON output block with realistic CLI output showing the "Auto-detected server:" prefix line and wall-of-JSON format; add jq pipeline example for readable extraction - #12: Fix Phase 3 WORKFLOW_ID capture to use `2>/dev/null | tail -1` before piping to jq, with comment explaining stdout/stderr separation

- Add 600 MB download notice after 'conductor server start' (#3) - Add idempotency note after 'conductor workflow create' (#4) - Note: README Slack badge uses join.slack.com format; CONTRIBUTING.md uses orkes-conductor.slack.com format — same invite token, tracked as #32

v1r3n · 2026-04-04T21:25:35Z

 **See a workflow execute in 2 minutes. Build your own in 5.**

-You need [Node.js](https://nodejs.org/) (v16+) installed. That's it.
+You need [Node.js](https://nodejs.org/) (v16+) and [Java](https://adoptium.net/) (21+) installed. That's it.


we shouldn't point to the distribution, different companies use different distribution. Adoptium is not an official distro for Java.

Fixed — Adoptium link removed. Now reads: "You need Node.js (v16+) and Java 21+ installed."

v1r3n · 2026-04-04T21:25:51Z


 ## Phase 1: See it work

+> **Prerequisite:** Java 21+ is required to run the Conductor server. Run `java --version` to check. [Install Java 21](https://adoptium.net/)


see above. Install Java 21 is sufficient.

Fixed — now just says "Install Java 21 if needed." with no distribution link.

v1r3n · 2026-04-04T21:26:03Z

 Wait for the server to start, then open the UI at [http://localhost:8080](http://localhost:8080).

+!!! note "Troubleshooting"
+    - **"Java not found" or server won't start?** Install Java 21+ from [Adoptium](https://adoptium.net/) and make sure `java -version` shows 21 or higher.


see above on the link to adoptium.

Fixed — troubleshooting note now says "Install Java 21+" with no Adoptium link.

Replace distribution-specific Java install links with generic "Install Java 21" language — different organizations use different JDK distributions and Adoptium is not an official distro. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

nthmost-orkes

done — removed all adoptium links, just says "install java 21" now

- README.md: keep docs.conductor-oss.org URLs (our canonical domain) - docs/quickstart/index.md: take main's @io-orkes/conductor-javascript require + fix npm install line to match

Use the actual sync endpoint POST /api/workflow/execute/{name}/{version} instead of the non-existent /api/workflow/{name}/run path. Reported in PR review feedback from Miguel Prieto.

Adds a hard rule: all REST endpoints, CLI commands, and code examples in docs must be verified against source before committing. Triggered by a hallucinated /run endpoint in the quickstart curl example (PR #930). CLAUDE.md: new repo-level guidance for Claude Code with verification checklist and key source locations. AGENTS.md: new Documentation Verification section with the same rules in a form readable by any AI coding agent.

Replace 'never do X' rules with step-by-step workflows for each content type: REST endpoints, CLI commands, SDK examples, expected output blocks. Core principle: open the source first, derive the doc from what you read. Applies to both AGENTS.md (any AI agent) and CLAUDE.md (Claude Code).

* Fix quickstart documentation: broken links, missing prerequisites, and troubleshooting - Fix two broken quickstart links in README.md (conductor-oss.org/quickstart -> docs.conductor-oss.org/quickstart/) - Add Node.js v16+ and Java 21+ to prerequisites in README.md - Add Java 21+ prerequisite to docs/quickstart/index.md - Add troubleshooting callout box for common issues (Java not found, port conflicts, Docker alternative) - conductor-oss#2: Add prominent Java 21 prerequisite callout before Phase 1 / Start Conductor - conductor-oss#5: Fix JS SDK package name from @conductor-oss/conductor-client to conductor-javascript-sdk; add npm install command - conductor-oss#13: Replace busy-wait `while True: pass` with `time.sleep(0.1)` + import time (CPU yield between poll cycles) - conductor-oss#14: Update Docker cURL --sync equivalent to use correct synchronous endpoint /api/workflow/{name}/run * MAESTRO: fix quickstart output format and jq pipeline (issues conductor-oss#11, conductor-oss#12) - conductor-oss#11: Replace clean JSON output block with realistic CLI output showing the "Auto-detected server:" prefix line and wall-of-JSON format; add jq pipeline example for readable extraction - conductor-oss#12: Fix Phase 3 WORKFLOW_ID capture to use `2>/dev/null | tail -1` before piping to jq, with comment explaining stdout/stderr separation * MAESTRO: fix README quickstart warnings (issues conductor-oss#3, conductor-oss#4) - Add 600 MB download notice after 'conductor server start' (conductor-oss#3) - Add idempotency note after 'conductor workflow create' (conductor-oss#4) - Note: README Slack badge uses join.slack.com format; CONTRIBUTING.md uses orkes-conductor.slack.com format — same invite token, tracked as conductor-oss#32 * MAESTRO: fix bug report template to be language-neutral (issue conductor-oss#31) * docs: remove Adoptium-specific links per reviewer feedback Replace distribution-specific Java install links with generic "Install Java 21" language — different organizations use different JDK distributions and Adoptium is not an official distro. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> * fix: correct curl equivalent for workflow start --sync Use the actual sync endpoint POST /api/workflow/execute/{name}/{version} instead of the non-existent /api/workflow/{name}/run path. Reported in PR review feedback from Miguel Prieto. * docs: add CLAUDE.md and doc verification rules to AGENTS.md Adds a hard rule: all REST endpoints, CLI commands, and code examples in docs must be verified against source before committing. Triggered by a hallucinated /run endpoint in the quickstart curl example (PR conductor-oss#930). CLAUDE.md: new repo-level guidance for Claude Code with verification checklist and key source locations. AGENTS.md: new Documentation Verification section with the same rules in a form readable by any AI coding agent. * docs: reframe doc rules as proactive workflow, not prohibitions Replace 'never do X' rules with step-by-step workflows for each content type: REST endpoints, CLI commands, SDK examples, expected output blocks. Core principle: open the source first, derive the doc from what you read. Applies to both AGENTS.md (any AI agent) and CLAUDE.md (Claude Code). ---------

nthmost-orkes added 5 commits March 16, 2026 15:39

MAESTRO: fix bug report template to be language-neutral (issue #31)

b35f760

nthmost-orkes requested a review from v1r3n March 27, 2026 08:46

Merge branch 'main' into fix/onboarding-phase1

6c17adb

v1r3n reviewed Apr 4, 2026

View reviewed changes

v1r3n requested changes Apr 4, 2026

View reviewed changes

nthmost-orkes commented Apr 5, 2026

View reviewed changes

nthmost-orkes requested a review from v1r3n April 6, 2026 16:42

nthmost-orkes added 4 commits April 6, 2026 09:44

chore: resolve merge conflicts with main

4513cb2

- README.md: keep docs.conductor-oss.org URLs (our canonical domain) - docs/quickstart/index.md: take main's @io-orkes/conductor-javascript require + fix npm install line to match

fix: correct curl equivalent for workflow start --sync

a3bb712

Use the actual sync endpoint POST /api/workflow/execute/{name}/{version} instead of the non-existent /api/workflow/{name}/run path. Reported in PR review feedback from Miguel Prieto.

v1r3n approved these changes Apr 6, 2026

View reviewed changes

Merge branch 'main' into fix/onboarding-phase1

8b9cda6

v1r3n merged commit 5d5f6a5 into main Apr 6, 2026
11 checks passed

v1r3n deleted the fix/onboarding-phase1 branch April 6, 2026 23:20

This was referenced Apr 7, 2026

docs: fix while True busy-wait and cURL sync endpoint in quickstart #955

Closed

Docker 'Using Docker instead' section: cURL sync equivalent is incomplete conductor-oss/getting-started#14

Closed

docs: remove Adoptium link from README prerequisites #986

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: onboarding quickstart accuracy improvements#930

fix: onboarding quickstart accuracy improvements#930
v1r3n merged 12 commits intomainfrom
fix/onboarding-phase1

nthmost-orkes commented Mar 26, 2026 •

edited

Loading

Uh oh!

v1r3n Apr 4, 2026

Uh oh!

nthmost-orkes Apr 6, 2026

Uh oh!

v1r3n Apr 4, 2026

Uh oh!

nthmost-orkes Apr 6, 2026

Uh oh!

v1r3n Apr 4, 2026

Uh oh!

nthmost-orkes Apr 6, 2026

Uh oh!

nthmost-orkes left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		## Phase 1: See it work

		> Prerequisite: Java 21+ is required to run the Conductor server. Run `java --version` to check. [Install Java 21](https://adoptium.net/)

Conversation

nthmost-orkes commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Issue conductor-oss/getting-started#1 (404 on conductor-oss.org/quickstart)

Test plan

Uh oh!

v1r3n Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

nthmost-orkes Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

v1r3n Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

nthmost-orkes Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

v1r3n Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

nthmost-orkes Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

nthmost-orkes left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

nthmost-orkes commented Mar 26, 2026 •

edited

Loading