docs: promote Workflows + introduce Primitives nav section#778
Draft
khaliqgant wants to merge 12 commits intomainfrom
Draft
docs: promote Workflows + introduce Primitives nav section#778khaliqgant wants to merge 12 commits intomainfrom
khaliqgant wants to merge 12 commits intomainfrom
Conversation
…tion
Nav changes:
- 'Basics' becomes 'Primitives' and groups related pages semantically:
* Message (expandable): Channels, DMs, Threads, Emoji reactions
* File (was 'File sharing')
* Auth (expandable): Permissions
* Schedule (was 'Scheduling')
- 'Spawning an agent' + 'Event handlers' move up into Getting Started
- Workflows promoted from a single bullet under Advanced to a top-level
section with 7 pages: Introduction, Quickstart, Builder API,
Patterns, Setup helpers, Common mistakes, Run from CLI
- CLI's 'Run workflows' folds into the Workflows section
- Advanced now only contains Cloud + Workforce
Nav renderer:
- NavItem gains optional children: NavItem[] for nested sub-items
- DocsNav.tsx renders children as an indented sub-list with left border
- getAllDocSlugs() walks the tree for static-generation coverage
New pages (stubbed with real content, not placeholders):
- workflows-introduction.mdx: landing, mental model, when to use
- workflows-quickstart.mdx: end-to-end 5-min example
- workflows-patterns.mdx: 80-to-100, lead+workers, multi-file edit,
cross-repo, supervisor, parallelism/waves
- workflows-setup-helpers.mdx: per-repo setup helper convention +
applySiblingLinks (landing in relay SDK #776)
- workflows-common-mistakes.mdx: the table every workflow author
needs once, ported from the writing-agent-relay-workflows skill
Content porting is from the two private Claude-Code skills
(writing-agent-relay-workflows and relay-80-100-workflow) so this
content is now public + addressable by URL.
DRAFT PR. Open questions for review:
- Should 'Permissions' be under Auth or its own primitive?
- 'Sending messages' acts as the Message landing — separate page or
umbrella?
- Should there be an 'Agent' primitive (for Spawning + Event handlers)
rather than putting them in Getting Started?
Primitives sub-items (Message, Auth) now render collapsed by default with a chevron toggle button. Rules: - Click the chevron to expand/collapse. Parent link stays active as a real nav link (clicking the label navigates to the parent page). - Auto-expands when the current URL is the parent or any of its children, so users don't lose their bearings after clicking a child link. - Chevron rotates 90deg when open; hover highlights the toggle. - Accessible: aria-expanded + aria-controls + aria-label on toggle. NavItemRow is now a component (uses useState) so each expandable item maintains independent open state. Non-expandable items (no children) render with the same layout as before — no chevron.
--sync-code was previously mentioned once in cli-cloud-commands.mdx
with no explanation. New workflow authors kept discovering the
'untracked files silently excluded' footgun the hard way.
Adds:
- A full section in cli-cloud-commands.mdx covering what --sync-code
does (tarballs git-tracked + staged files), when to use it
(~always), when not to (rare cases), and the typical flow.
- A cloud-execution block in workflows-introduction.mdx showing the
common invocation pattern + linking to the full reference.
- A 'Run it in the cloud' section in workflows-quickstart.mdx that
walks through stage-then-sync-run-sync-back.
Cross-links from the intro and quickstart to the cli page section.
Reinforces the existing 'untracked files excluded' entry in
workflows-common-mistakes.mdx.
Corrects the staging-is-enough claim that appeared in the prior commit. --sync-code tarballs HEAD: ✅ Committed files (pushed or local) ❌ Staged-but-not-committed ❌ Unstaged edits ❌ Untracked files Updates all four affected pages (cli-cloud-commands, workflows- introduction, workflows-quickstart, workflows-common-mistakes) with consistent wording: 'commit' rather than 'git add', with a callout that pushing isn't required but committing is.
The CLI install section rendered the two install options as a bullet list with inline backtick code, which crammed the long curl URL onto the same visual line as the label and wrapped awkwardly. Switch to the same CodeGroup pattern used by the SDK install block higher on the page — npm vs install-script tabs, each with its own code block. Also adds a 'Start a local broker and spawn agents' intro line before the subsequent command block.
Reorder the CodeGroup so install script shows first (becomes the default tab), label it 'recommended', and add a one-sentence note explaining why — install script pulls the native broker binary for the user's platform alongside the CLI, while npm only gets the JavaScript entrypoint.
Let readers discover the pattern where a host agent (Claude, Codex, etc.) spawns and manages its own team of sub-agents from inside a session, via the running-headless-orchestrator skill. Two install paths shown (prpm as recommended with the --as host[,host] variant, plus the direct skills-add command as an alternative), and a one-line prompt example so readers see what to tell the host once the skill is loaded.
…framing
'A workflow is a DAG of steps' was only true for the default pattern.
The SDK ships 25 swarm patterns (debate, mesh, review-loop, saga,
circuit-breaker, swarm, etc.) — many are NOT DAGs. Replaced with a
grouped table (DAG/trees, hubs, iterative loops, non-fixed, selection,
error-handling) plus a note that hub patterns auto-harden with a
supervisor while plain dag/pipeline don't.
Step types were understated too. WorkflowStepType is 'agent' |
'deterministic' | 'worktree' | 'integration'. Added worktree + integration.
Also reframed the top of the page to make two things explicit:
1. Workflows compose the primitives (channels, DMs, threads, files,
scheduling) — they don't replace them. Links to each primitive page
for discoverability.
2. Workflows are repeatable — the point is that you write them once
and run them N times, share them, schedule them, resume from
partial failure. Added this as a first-class 'why' bullet and a
paragraph about orchestration at scale.
…skills block
Two corrections + one addition:
1. GitHub primitive moved from top-level Primitives to Workflows.
It's a workflow-specific primitive (integration step shaped for
workflow(), not a general Relay primitive like channels/DMs), so
it belongs alongside Patterns and Setup helpers under Workflows.
2. workflows-introduction 'how workflows use primitives' section
separates top-level Relay primitives (channels/DMs/threads/files/
scheduling) from workflow-specific primitives (GitHub). One
trailing paragraph introduces the latter category.
3. New 'Let an agent write your workflows' section at the bottom of
workflows-introduction. Same install-box pattern as the headless
orchestrator block in quickstart:
- prpm (recommended, with --as claude[,codex] variants)
- skills add (alternative)
Mentions both writing-agent-relay-workflows (core authoring) and
relay-80-100-workflow (validation-gate layer) with a one-line role
description for each + two example prompts.
Dropped the standalone GitHubClient client-only usage block — the primitive is used WITHIN a workflow, not as a standalone imperative client. Kept the workflow integration step (createGitHubStep) as the one canonical usage example. Updated intro to state the primitive is bundled with the SDK (no separate install), and switched the import path to the bundled subpath `@agent-relay/sdk/github`. This is the target state — the bundling lands in a sibling SDK PR so this doc is accurate on merge.
4 tasks
… HEAD) Previous iterations overshot in both directions — first said staging was enough, then corrected to 'only committed.' Actual ground truth from reading relay's createTarball (packages/cloud/src/workflows.ts): 1. git ls-files -z -> tracked paths 2. tar.create() reads working-tree contents of those paths So: - Committed files -> yes - Committed + modified -> yes (working-tree contents) - Staged new file (added, not committed) -> yes - Untracked (never added) -> NO - Gitignored -> NO `git add` is enough. Commit not required. No `git clone` fallback if --sync-code is omitted — sandbox starts with empty $HOME. Affected pages: cli-cloud-commands (full explainer), workflows- introduction (cloud exec block), workflows-quickstart (Run-in-cloud section), workflows-common-mistakes (one-liner). All now consistent.
The example prompt implied the skill would auto-invoke. Make the skill name explicit so users see how to reference it in their own prompts. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Restructures the docs navigation so Workflows is addressable as a top-level flagship section (not buried as a single bullet in "Advanced"), and groups the Basics pages into a more scannable "Primitives" section with nested sub-items.
Why
Current
reference-workflows.mdxis 180 lines of pure API reference because everything else — patterns, gotchas, helpers, 80-to-100 — lives in two Claude-Code-only skills. This PR moves that content into public, addressable docs.Also, features like
applySiblingLinks(landing in relay SDK #776) have no home to be documented without this restructure.Nav changes
Before:
After:
Technical details
Nav renderer:
NavItemgets optionalchildren: NavItem[]for nested sub-items.DocsNav.tsxrenders children as an indented sub-list with a left border.getAllDocSlugs()recurses through the tree for static-generation coverage.navChildren) — minimal visual change beyond the indent.New pages (~1100 lines total, real content not placeholders):
workflows-introduction.mdxworkflows-quickstart.mdxworkflows-patterns.mdxwriting-agent-relay-workflows+relay-80-100-workflowskillsworkflows-setup-helpers.mdxapplySiblingLinksworkflows-common-mistakes.mdxDraft because
Open questions I'd love your call on:
Permissions— under Auth (current) or its own primitive?Sending messages— currently acts as the Message landing page. Should it be a separate page with Message as an umbrella, or stay as-is?Agentprimitive (for Spawning + Event handlers) rather than putting them in Getting Started?reference-workflows.mdx— I kept the slug for redirect compat but relabeled the nav to "Builder API". Rename the file too (with a redirect)?applySiblingLinksreference — currently mentioned inworkflows-setup-helpers.mdxbut the SDK PR (feat(sdk): applySiblingLinks — link sibling-repo packages during workflow setup #776) isn't merged yet. Left the link pointing at the source file; swap to hosted typedoc once it exists.Test plan
tsc --noEmitclean for nav/renderer changesFollow-ups
reference-workflows.mdxcontent as-is).Workflows → Examplespage or link to a/examplesdirectory in the repo.applySiblingLinksreference to a typedoc-rendered page once the SDK docs pipeline lands.