docs: add workstream (parallel features) documentation#913
Open
SalesTeamToolbox wants to merge 12 commits intogsd-build:mainfrom
Open
docs: add workstream (parallel features) documentation#913SalesTeamToolbox wants to merge 12 commits intogsd-build:mainfrom
SalesTeamToolbox wants to merge 12 commits intogsd-build:mainfrom
Conversation
Add resolvePlanningDir() and buildPaths() to core.cjs, then thread the paths object through all 11 modules. In flat mode (no workstreams directory), all paths resolve identically to the previous hardcoded .planning/ paths — zero behavior change verified via init progress diff. - core.cjs: new resolvePlanningDir(), buildPaths(), toPosixPath() - gsd-tools.cjs: parse --ws flag, build paths, pass to all dispatches - All 10 lib modules: accept optional paths param, use p.* instead of hardcoded path.join(cwd, '.planning', ...) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add lib/workstream.cjs with four commands:
- workstream create <name>: creates .planning/workstreams/{name}/ with
STATE.md and phases/ scaffolding. On first create, auto-migrates
existing flat .planning/ files (ROADMAP, STATE, REQUIREMENTS, phases/)
into a named workstream based on current milestone.
- workstream list: enumerates all workstreams with status, phase counts
- workstream status <name>: detailed status for a single workstream
- workstream complete <name>: archives workstream to milestones/
Migration is transparent — first workstream create detects flat mode,
moves scoped files to workstreams/{milestone-slug}/, leaves shared
files (PROJECT.md, config.json, todos/, research/) in place.
Backward compat verified: agent42 flat-mode output unchanged.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add workstream flag passthrough to core workflow files: - references/workstream-flag.md: shared pattern doc for WS extraction - workflows/execute-phase.md: WS init, dynamic paths in subagent <files_to_read> and commit --files - workflows/execute-plan.md: WS init, dynamic phase_dir paths, per-workstream agent tracking files - workflows/new-milestone.md: WS init, dynamic paths in researcher/ roadmapper subagent prompts and all commit commands Remaining workflows (transition, discuss-phase, etc.) need the same treatment in a follow-up — core agent still running. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
… updates Adds --ws flag extraction and dynamic path variables to three more core workflows. execute-plan.md gets additional edits beyond the partial commit. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds --ws flag extraction and ${GSD_WS} passthrough to all gsd-tools.cjs
invocations across 24 workflow files. Replaces hardcoded .planning/
paths with init-derived variables (state_path, roadmap_path, phase_dir,
etc.) for workstream-scoped resources. Shared paths (PROJECT.md,
milestones/, codebase/, config.json, todos/) left unchanged.
4 files correctly skipped (no gsd-tools calls): discovery-phase.md,
help.md, list-phase-assumptions.md, update.md.
Backward compat verified: init progress output byte-identical to baseline.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Active workstream detection: .planning/active-workstream file auto-detected when --ws flag not passed - workstream set/get commands: persist and query active workstream - workstream progress: cross-workstream summary with phase counts, plan counts, and progress percentages - Commit prefixes: [ws-name] prepended to commit messages when workstream is active New functions: getActiveWorkstream(), setActiveWorkstream() in core.cjs New commands: workstream set|get|progress in workstream.cjs Modified: cmdCommit() accepts ws param for prefix injection Backward compat verified: init progress output identical in flat mode. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds Step 0 (Workstream Detection) that checks if an existing milestone is in-flight before starting a new one. If so, offers parallel workstream creation with automatic migration of existing flat files. Handles three cases: flat mode with conflict, already in workstream mode, and greenfield. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…s quoting - new-milestone Step 0: ask milestone name before workstream create (slug needs name) - workstream create: auto-set active workstream (no separate set command needed) - complete-milestone: offer workstream archival after milestone ships - execGit: use execFileSync to avoid shell quoting issues with brackets on Windows Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Blockers fixed:
- cmdWorkstreamComplete now clears active-workstream file
- migrateToWorkstreams rolls back on partial failure
- resolvePlanningDir no longer silently falls back to phantom 'default' ws
- new-milestone Step 7 no longer overwrites GSD_WS set by Step 0
- complete-milestone complete_workstream step rewritten to avoid double-archive
Code quality:
- Same-day archive collision prevention (suffix counter)
- Failed create no longer blocks retry (check STATE.md not just dir)
- generate-slug guards against empty result
- Redundant inline requires removed from workstream.cjs
- Path-traversal validation added to migrateToWorkstreams
Workflow gaps (14 files):
- 7 files now have bash WS extraction block (were using ${GSD_WS} undefined)
- 7 files prose-only extraction replaced with standard bash block
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…gaps
- isGitIgnored migrated to execFileSync (consistent with execGit fix)
- cmdWorkstreamComplete: archive loop now has rollback on failure
- cmdWorkstreamComplete/Status: path-traversal validation on name param
- quick.md: add missing WS extraction block (last workflow gap)
- plan-phase.md: auto-advance Task spawn now passes ${GSD_WS}
- complete-milestone.md: simplify redundant WS_NAME re-extraction
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Document the parallel workstreams feature — how to run multiple Claude Code instances on independent features with isolated planning state. Co-Authored-By: Claude Opus 4.6 <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
Context
The workstream feature enables running multiple Claude Code instances in parallel, each working on an independent milestone with isolated planning state (ROADMAP, STATE, REQUIREMENTS, phases). Project-level files (PROJECT.md, config, research, todos) remain shared. This documentation covers:
/gsd:new-milestoneTest plan
🤖 Generated with Claude Code